@splendidlabz/utils 1.8.2 → 1.9.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @splendidlabz/utils
 
+## 1.9.0
+
+### Minor Changes
+
+- 8f2cb34: - 48406c69 Add JSDocs for events
+  - 304b5310 Utils: Add runCallback
+
 ## 1.8.2
 
 ### Patch Changes

package/dist/cjs/dom/events.cjs

@@ -20,7 +20,6 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var events_exports = {};
 __export(events_exports, {
   addListeners: () => addListeners,
-  createListeners: () => createListeners,
   dispatchEvent: () => dispatchEvent,
   removeListeners: () => removeListeners,
   updateEvent: () => updateEvent
@@ -51,44 +50,9 @@ function updateEvent(event, updates) {
     ...updates
   });
 }
-function createListeners(listeners) {
-  listeners = listeners || [];
-  listeners.forEach((listener) => {
-    const { node, event, handler } = listener;
-    node.addEventListener(event, handler);
-  });
-  return {
-    get list() {
-      return listeners;
-    },
-    add({ node, event, handler }) {
-      listeners.push({ node, event, handler });
-      node.addEventListener(event, handler);
-    },
-    remove({ node, event, handler }) {
-      const index = listeners.findIndex((listener) => {
-        if (listener.node === node && listener.event === event && listener.handler === handler) {
-          return true;
-        }
-        return false;
-      });
-      if (index !== -1) {
-        listeners.splice(index, 1);
-        node.removeEventListener(event, handler);
-      }
-    },
-    clear() {
-      listeners.forEach(({ node, event, handler }) => {
-        listeners = [];
-        node.removeEventListener(event, handler);
-      });
-    }
-  };
-}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   addListeners,
-  createListeners,
   dispatchEvent,
   removeListeners,
   updateEvent

package/dist/cjs/dom/index.cjs

@@ -37,7 +37,6 @@ __export(dom_exports, {
   checkForAccessibleName: () => checkForAccessibleName,
   cookies: () => cookies,
   copyRichText: () => copyRichText,
-  createListeners: () => createListeners,
   dispatchEvent: () => dispatchEvent,
   em: () => em,
   findScrollContainer: () => findScrollContainer,
@@ -231,40 +230,6 @@ function updateEvent(event, updates) {
     ...updates
   });
 }
-function createListeners(listeners) {
-  listeners = listeners || [];
-  listeners.forEach((listener) => {
-    const { node, event, handler } = listener;
-    node.addEventListener(event, handler);
-  });
-  return {
-    get list() {
-      return listeners;
-    },
-    add({ node, event, handler }) {
-      listeners.push({ node, event, handler });
-      node.addEventListener(event, handler);
-    },
-    remove({ node, event, handler }) {
-      const index = listeners.findIndex((listener) => {
-        if (listener.node === node && listener.event === event && listener.handler === handler) {
-          return true;
-        }
-        return false;
-      });
-      if (index !== -1) {
-        listeners.splice(index, 1);
-        node.removeEventListener(event, handler);
-      }
-    },
-    clear() {
-      listeners.forEach(({ node, event, handler }) => {
-        listeners = [];
-        node.removeEventListener(event, handler);
-      });
-    }
-  };
-}
 
 // src/dom/observers/observer.js
 function useObserverMethodOnTarget(target, observer, method = "observe", options = void 0) {
@@ -1229,7 +1194,6 @@ function scrambleText(text) {
   checkForAccessibleName,
   cookies,
   copyRichText,
-  createListeners,
   dispatchEvent,
   em,
   findScrollContainer,

package/dist/cjs/lib/functions/callback.cjs

@@ -0,0 +1,31 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/lib/functions/callback.js
+var callback_exports = {};
+__export(callback_exports, {
+  runCallback: () => runCallback
+});
+module.exports = __toCommonJS(callback_exports);
+function runCallback(fn, ...data) {
+  if (typeof fn === "function") fn(data);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  runCallback
+});

package/dist/esm/dom/events.js

@@ -24,43 +24,8 @@ function updateEvent(event, updates) {
     ...updates
   });
 }
-function createListeners(listeners) {
-  listeners = listeners || [];
-  listeners.forEach((listener) => {
-    const { node, event, handler } = listener;
-    node.addEventListener(event, handler);
-  });
-  return {
-    get list() {
-      return listeners;
-    },
-    add({ node, event, handler }) {
-      listeners.push({ node, event, handler });
-      node.addEventListener(event, handler);
-    },
-    remove({ node, event, handler }) {
-      const index = listeners.findIndex((listener) => {
-        if (listener.node === node && listener.event === event && listener.handler === handler) {
-          return true;
-        }
-        return false;
-      });
-      if (index !== -1) {
-        listeners.splice(index, 1);
-        node.removeEventListener(event, handler);
-      }
-    },
-    clear() {
-      listeners.forEach(({ node, event, handler }) => {
-        listeners = [];
-        node.removeEventListener(event, handler);
-      });
-    }
-  };
-}
 export {
   addListeners,
-  createListeners,
   dispatchEvent,
   removeListeners,
   updateEvent

package/dist/esm/dom/index.js

@@ -134,40 +134,6 @@ function updateEvent(event, updates) {
     ...updates
   });
 }
-function createListeners(listeners) {
-  listeners = listeners || [];
-  listeners.forEach((listener) => {
-    const { node, event, handler } = listener;
-    node.addEventListener(event, handler);
-  });
-  return {
-    get list() {
-      return listeners;
-    },
-    add({ node, event, handler }) {
-      listeners.push({ node, event, handler });
-      node.addEventListener(event, handler);
-    },
-    remove({ node, event, handler }) {
-      const index = listeners.findIndex((listener) => {
-        if (listener.node === node && listener.event === event && listener.handler === handler) {
-          return true;
-        }
-        return false;
-      });
-      if (index !== -1) {
-        listeners.splice(index, 1);
-        node.removeEventListener(event, handler);
-      }
-    },
-    clear() {
-      listeners.forEach(({ node, event, handler }) => {
-        listeners = [];
-        node.removeEventListener(event, handler);
-      });
-    }
-  };
-}
 
 // src/dom/observers/observer.js
 function useObserverMethodOnTarget(target, observer, method = "observe", options = void 0) {
@@ -1131,7 +1097,6 @@ export {
   checkForAccessibleName,
   cookies,
   copyRichText,
-  createListeners,
   dispatchEvent,
   em,
   findScrollContainer,

package/dist/esm/lib/functions/callback.js

@@ -0,0 +1,7 @@
+// src/lib/functions/callback.js
+function runCallback(fn, ...data) {
+  if (typeof fn === "function") fn(data);
+}
+export {
+  runCallback
+};

package/dist/types/dom/events.d.cts

@@ -1,20 +1,92 @@
-declare function addListeners(listeners: any): void;
-declare function removeListeners(listeners: any): void;
-declare function dispatchEvent(node: any, eventName: any, detail: any, options?: {}): void;
-declare function updateEvent(event: any, updates: any): CustomEvent<any>;
-declare function createListeners(listeners: any): {
-    readonly list: any;
-    add({ node, event, handler }: {
-        node: any;
-        event: any;
-        handler: any;
-    }): void;
-    remove({ node, event, handler }: {
-        node: any;
-        event: any;
-        handler: any;
-    }): void;
-    clear(): void;
+/**
+ * @typedef {Object} EventListener
+ * @property {Element} node - The DOM element to attach the event listener to
+ * @property {string} event - The event type (e.g., 'click', 'keydown')
+ * @property {Function} handler - The event handler function
+ */
+/**
+ * @typedef {Object} ListenerManager
+ * @property {EventListener[]} list - Array of current event listeners
+ * @property {function(EventListener): void} add - Add a new event listener
+ * @property {function(EventListener): void} remove - Remove an event listener
+ * @property {function(): void} clear - Remove all event listeners
+ */
+/**
+ * @typedef {Object} CustomEventOptions
+ * @property {boolean} [bubbles=false] - Whether the event bubbles up through the DOM
+ * @property {boolean} [cancelable=false] - Whether the event can be canceled
+ * @property {boolean} [composed=false] - Whether the event will trigger listeners outside of a shadow root
+ */
+/**
+ * Adds multiple event listeners to their respective DOM elements
+ * @param {EventListener[]} listeners - Array of listener objects
+ */
+declare function addListeners(listeners: EventListener[]): void;
+/**
+ * Removes multiple event listeners from their respective DOM elements
+ * @param {EventListener[]} listeners - Array of listener objects
+ */
+declare function removeListeners(listeners: EventListener[]): void;
+/**
+ * Dispatches a custom event from a DOM node
+ * @param {Element} node - The DOM element to dispatch the event from
+ * @param {string} eventName - The name of the custom event
+ * @param {*} detail - The detail data to include with the event
+ * @param {CustomEventOptions} [options={}] - Additional event options
+ */
+declare function dispatchEvent(node: Element, eventName: string, detail: any, options?: CustomEventOptions): void;
+/**
+ * Creates a new CustomEvent with updated properties from an existing event
+ * @param {Event} event - The original event object
+ * @param {Object} updates - Properties to update in the new event
+ * @return {CustomEvent} A new CustomEvent with updated properties
+ */
+declare function updateEvent(event: Event, updates: any): CustomEvent;
+type EventListener = {
+    /**
+     * - The DOM element to attach the event listener to
+     */
+    node: Element;
+    /**
+     * - The event type (e.g., 'click', 'keydown')
+     */
+    event: string;
+    /**
+     * - The event handler function
+     */
+    handler: Function;
+};
+type ListenerManager = {
+    /**
+     * - Array of current event listeners
+     */
+    list: EventListener[];
+    /**
+     * - Add a new event listener
+     */
+    add: (arg0: EventListener) => void;
+    /**
+     * - Remove an event listener
+     */
+    remove: (arg0: EventListener) => void;
+    /**
+     * - Remove all event listeners
+     */
+    clear: () => void;
+};
+type CustomEventOptions = {
+    /**
+     * - Whether the event bubbles up through the DOM
+     */
+    bubbles?: boolean;
+    /**
+     * - Whether the event can be canceled
+     */
+    cancelable?: boolean;
+    /**
+     * - Whether the event will trigger listeners outside of a shadow root
+     */
+    composed?: boolean;
 };
 
-export { addListeners, createListeners, dispatchEvent, removeListeners, updateEvent };
+export { type CustomEventOptions, type EventListener, type ListenerManager, addListeners, dispatchEvent, removeListeners, updateEvent };

package/dist/types/dom/index.d.cts

@@ -6,7 +6,7 @@ export { boundingBox, boundingBoxRelativeToAncestor } from './bounding-box.cjs';
 export { copyRichText } from './clipboard.cjs';
 export { cookies, getCookie } from './cookie.cjs';
 export { getCSSValue, getCSSVar, setCSSValue, setCSSVar } from './css-vars.cjs';
-export { addListeners, createListeners, dispatchEvent, removeListeners, updateEvent } from './events.cjs';
+export { CustomEventOptions, EventListener, ListenerManager, addListeners, dispatchEvent, removeListeners, updateEvent } from './events.cjs';
 export { Focusable, Focusables, getFocusableElements } from './focusable.cjs';
 export { em, getUnit, lh, rem, toPx } from './font-size.cjs';
 export { getAncestorWithSiblings, getChildrenElements, getElement, getNodeType, getParentElement, getSelfIndex, getSiblingElements, isAncestor } from './get-element.cjs';

package/dist/types/lib/functions/callback.d.cts

@@ -0,0 +1,8 @@
+/**
+ * Safely executes a callback function if it's a function
+ * @param {Function|*} fn - The potential callback function
+ * @param {...*} data - Data arguments to pass to the callback
+ */
+declare function runCallback(fn: Function | any, ...data: any[]): void;
+
+export { runCallback };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@splendidlabz/utils",
-  "version": "1.8.2",
+  "version": "1.9.0",
   "description": "",
   "type": "module",
   "sideEffects": false,

package/src/dom/events.js

@@ -1,26 +1,67 @@
+/**
+ * @typedef {Object} EventListener
+ * @property {Element} node - The DOM element to attach the event listener to
+ * @property {string} event - The event type (e.g., 'click', 'keydown')
+ * @property {Function} handler - The event handler function
+ */
+
+/**
+ * @typedef {Object} ListenerManager
+ * @property {EventListener[]} list - Array of current event listeners
+ * @property {function(EventListener): void} add - Add a new event listener
+ * @property {function(EventListener): void} remove - Remove an event listener
+ * @property {function(): void} clear - Remove all event listeners
+ */
+
+/**
+ * @typedef {Object} CustomEventOptions
+ * @property {boolean} [bubbles=false] - Whether the event bubbles up through the DOM
+ * @property {boolean} [cancelable=false] - Whether the event can be canceled
+ * @property {boolean} [composed=false] - Whether the event will trigger listeners outside of a shadow root
+ */
+
+/**
+ * Adds multiple event listeners to their respective DOM elements
+ * @param {EventListener[]} listeners - Array of listener objects
+ */
 export function addListeners(listeners) {
   listeners.forEach(({ node, event, handler }) => {
     node.addEventListener(event, handler)
   })
 }
 
+/**
+ * Removes multiple event listeners from their respective DOM elements
+ * @param {EventListener[]} listeners - Array of listener objects
+ */
 export function removeListeners(listeners) {
   listeners.forEach(({ node, event, handler }) => {
     node.removeEventListener(event, handler)
   })
 }
 
-// Dispatch a custom event from a Node.
+/**
+ * Dispatches a custom event from a DOM node
+ * @param {Element} node - The DOM element to dispatch the event from
+ * @param {string} eventName - The name of the custom event
+ * @param {*} detail - The detail data to include with the event
+ * @param {CustomEventOptions} [options={}] - Additional event options
+ */
 export function dispatchEvent(node, eventName, detail, options = {}) {
   node.dispatchEvent(
     new CustomEvent(eventName, {
       ...options,
       detail,
-    })
+    }),
   )
 }
 
-// Updates an event with new properties
+/**
+ * Creates a new CustomEvent with updated properties from an existing event
+ * @param {Event} event - The original event object
+ * @param {Object} updates - Properties to update in the new event
+ * @return {CustomEvent} A new CustomEvent with updated properties
+ */
 export function updateEvent(event, updates) {
   const { type, ...rest } = event
   return new CustomEvent(event.type, {
@@ -28,50 +69,3 @@ export function updateEvent(event, updates) {
     ...updates,
   })
 }
-
-// Doesn't seem to be used anywhere now.
-// Switch to addListeners and removeListeners instead
-export function createListeners(listeners) {
-  listeners = listeners || []
-
-  listeners.forEach(listener => {
-    const { node, event, handler } = listener
-    node.addEventListener(event, handler)
-  })
-
-  return {
-    get list() {
-      return listeners
-    },
-
-    add({ node, event, handler }) {
-      listeners.push({ node, event, handler })
-      node.addEventListener(event, handler)
-    },
-
-    remove({ node, event, handler }) {
-      const index = listeners.findIndex(listener => {
-        if (
-          listener.node === node &&
-          listener.event === event &&
-          listener.handler === handler
-        ) {
-          return true
-        }
-        return false
-      })
-
-      if (index !== -1) {
-        listeners.splice(index, 1)
-        node.removeEventListener(event, handler)
-      }
-    },
-
-    clear() {
-      listeners.forEach(({ node, event, handler }) => {
-        listeners = []
-        node.removeEventListener(event, handler)
-      })
-    },
-  }
-}

package/src/lib/functions/callback.js

@@ -0,0 +1,8 @@
+/**
+ * Safely executes a callback function if it's a function
+ * @param {Function|*} fn - The potential callback function
+ * @param {...*} data - Data arguments to pass to the callback
+ */
+export function runCallback(fn, ...data) {
+  if (typeof fn === 'function') fn(data)
+}