@briannorman9/eli-utils 1.0.0

package/README.md

@@ -0,0 +1,81 @@
+# @briannorman9/eli-utils
+
+Utility functions for ELI web experiments.
+
+## Installation
+
+```bash
+npm install @briannorman9/eli-utils
+```
+
+## Usage
+
+In your ELI project code, you can import utils using the special `@eli/utils` import syntax (the server will automatically resolve it to the installed `eli-utils` package):
+
+```javascript
+import utils from '@eli/utils';
+
+// Wait for an element to appear
+utils.waitForElement('#myElement').then(element => {
+  console.log('Element found:', element);
+});
+
+// Wait until a condition is met
+utils.waitUntil(() => document.readyState === 'complete');
+
+// DOM manipulation
+utils.addClass('#myButton', 'active');
+utils.removeClass('#myButton', 'inactive');
+
+// Event handling
+utils.on('#myButton', 'click', () => console.log('Clicked!'));
+
+// Cookies
+const userId = utils.getCookie('userId');
+utils.setCookie('userId', '12345', 30);
+
+// Query parameters
+const campaign = utils.getQueryParam('campaign');
+
+// Custom events
+utils.triggerEvent('experimentLoaded', { variant: 'v1' });
+```
+
+## API Reference
+
+### Element Utilities
+
+- `waitForElement(selector)` - Wait for element to appear (waits indefinitely)
+- `waitUntil(condition, interval)` - Wait until condition is true (waits indefinitely, checks every `interval` ms, default: 100ms)
+- `select(selector, context)` - Select single element
+- `selectAll(selector, context)` - Select multiple elements
+- `addClass(element, className)` - Add class to element
+- `removeClass(element, className)` - Remove class from element
+- `toggleClass(element, className)` - Toggle class on element
+- `hasClass(element, className)` - Check if element has class
+
+### Event Utilities
+
+- `on(element, event, handler)` - Add event listener
+- `off(element, event, handler)` - Remove event listener
+- `delegate(parent, selector, event, handler)` - Event delegation
+- `triggerEvent(eventName, data, target)` - Trigger custom event
+
+### Cookie Utilities
+
+- `getCookie(name)` - Get cookie value
+- `setCookie(name, value, days, path)` - Set cookie
+
+### URL Utilities
+
+- `getQueryParam(name, url)` - Get URL query parameter
+
+### Viewport Utilities
+
+- `getViewport()` - Get viewport dimensions
+- `isInViewport(element, threshold)` - Check if element is in viewport
+- `scrollIntoView(element, options)` - Scroll element into view
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,262 @@
+// ELI Utils - Utility functions for web experiments
+// This package can be installed via: npm install @briannorman9/eli-utils
+// Then imported in variant code using: import utils from '@eli/utils';
+// (The server automatically resolves @eli/utils to the @briannorman9/eli-utils package)
+
+export default {
+  /**
+   * Wait for an element to appear in the DOM
+   * @param {string|Element} selector - CSS selector or element
+   * @returns {Promise<Element>} Promise that resolves with the element (waits indefinitely)
+   */
+  waitForElement: function(selector) {
+    return new Promise((resolve) => {
+      // If selector is already an element, return it immediately
+      if (selector instanceof Element) {
+        resolve(selector);
+        return;
+      }
+
+      // Check if element already exists
+      const element = document.querySelector(selector);
+      if (element) {
+        resolve(element);
+        return;
+      }
+
+      // Set up MutationObserver to watch for element
+      const observer = new MutationObserver((mutations, obs) => {
+        const element = document.querySelector(selector);
+        if (element) {
+          obs.disconnect();
+          resolve(element);
+        }
+      });
+
+      observer.observe(document.body, {
+        childList: true,
+        subtree: true
+      });
+    });
+  },
+
+  /**
+   * Wait until a condition function returns true
+   * @param {Function} condition - Function that returns a boolean
+   * @param {number} interval - Check interval in milliseconds (default: 100)
+   * @returns {Promise} Promise that resolves when condition is met (waits indefinitely)
+   */
+  waitUntil: function(condition, interval = 100) {
+    return new Promise((resolve, reject) => {
+      const checkCondition = () => {
+        try {
+          if (condition()) {
+            resolve();
+          } else {
+            setTimeout(checkCondition, interval);
+          }
+        } catch (error) {
+          reject(error);
+        }
+      };
+
+      checkCondition();
+    });
+  },
+
+  /**
+   * Get a cookie value by name
+   * @param {string} name - Cookie name
+   * @returns {string|null} Cookie value or null if not found
+   */
+  getCookie: function(name) {
+    const value = `; ${document.cookie}`;
+    const parts = value.split(`; ${name}=`);
+    if (parts.length === 2) {
+      return parts.pop().split(';').shift();
+    }
+    return null;
+  },
+
+  /**
+   * Set a cookie
+   * @param {string} name - Cookie name
+   * @param {string} value - Cookie value
+   * @param {number} days - Number of days until expiration (default: 365)
+   * @param {string} path - Cookie path (default: '/')
+   */
+  setCookie: function(name, value, days = 365, path = '/') {
+    const expires = new Date();
+    expires.setTime(expires.getTime() + (days * 24 * 60 * 60 * 1000));
+    document.cookie = `${name}=${value};expires=${expires.toUTCString()};path=${path}`;
+  },
+
+  /**
+   * Get a URL query parameter value
+   * @param {string} name - Parameter name
+   * @param {string} url - Optional URL (defaults to current window location)
+   * @returns {string|null} Parameter value or null if not found
+   */
+  getQueryParam: function(name, url = window.location.href) {
+    const urlObj = new URL(url);
+    return urlObj.searchParams.get(name);
+  },
+
+  /**
+   * Trigger a custom event
+   * @param {string} eventName - Event name
+   * @param {Object} data - Event data
+   * @param {Element|string} target - Target element (defaults to document)
+   */
+  triggerEvent: function(eventName, data = {}, target = document) {
+    const targetEl = typeof target === 'string' ? document.querySelector(target) : target;
+    if (targetEl) {
+      const event = new CustomEvent(eventName, { detail: data });
+      targetEl.dispatchEvent(event);
+    }
+  },
+
+  /**
+   * Select a single element
+   * @param {string} selector - CSS selector
+   * @param {Element} context - Context element (defaults to document)
+   * @returns {Element|null} Element or null if not found
+   */
+  select: function(selector, context = document) {
+    return context.querySelector(selector);
+  },
+
+  /**
+   * Select multiple elements
+   * @param {string} selector - CSS selector
+   * @param {Element} context - Context element (defaults to document)
+   * @returns {NodeList} NodeList of elements
+   */
+  selectAll: function(selector, context = document) {
+    return context.querySelectorAll(selector);
+  },
+
+  /**
+   * Add a class to an element
+   * @param {Element|string} element - Element or selector
+   * @param {string} className - Class name to add
+   */
+  addClass: function(element, className) {
+    const el = typeof element === 'string' ? document.querySelector(element) : element;
+    if (el) el.classList.add(className);
+  },
+
+  /**
+   * Remove a class from an element
+   * @param {Element|string} element - Element or selector
+   * @param {string} className - Class name to remove
+   */
+  removeClass: function(element, className) {
+    const el = typeof element === 'string' ? document.querySelector(element) : element;
+    if (el) el.classList.remove(className);
+  },
+
+  /**
+   * Toggle a class on an element
+   * @param {Element|string} element - Element or selector
+   * @param {string} className - Class name to toggle
+   */
+  toggleClass: function(element, className) {
+    const el = typeof element === 'string' ? document.querySelector(element) : element;
+    if (el) el.classList.toggle(className);
+  },
+
+  /**
+   * Check if an element has a class
+   * @param {Element|string} element - Element or selector
+   * @param {string} className - Class name to check
+   * @returns {boolean} True if element has the class
+   */
+  hasClass: function(element, className) {
+    const el = typeof element === 'string' ? document.querySelector(element) : element;
+    return el ? el.classList.contains(className) : false;
+  },
+
+  /**
+   * Add an event listener
+   * @param {Element|string} element - Element or selector
+   * @param {string} event - Event name
+   * @param {Function} handler - Event handler
+   */
+  on: function(element, event, handler) {
+    const el = typeof element === 'string' ? document.querySelector(element) : element;
+    if (el) el.addEventListener(event, handler);
+  },
+
+  /**
+   * Remove an event listener
+   * @param {Element|string} element - Element or selector
+   * @param {string} event - Event name
+   * @param {Function} handler - Event handler
+   */
+  off: function(element, event, handler) {
+    const el = typeof element === 'string' ? document.querySelector(element) : element;
+    if (el) el.removeEventListener(event, handler);
+  },
+
+  /**
+   * Event delegation - attach event to parent, handle on children
+   * @param {Element|string} parent - Parent element or selector
+   * @param {string} selector - Child selector to match
+   * @param {string} event - Event name
+   * @param {Function} handler - Event handler
+   */
+  delegate: function(parent, selector, event, handler) {
+    const parentEl = typeof parent === 'string' ? document.querySelector(parent) : parent;
+    if (parentEl) {
+      parentEl.addEventListener(event, (e) => {
+        if (e.target.matches(selector) || e.target.closest(selector)) {
+          handler(e);
+        }
+      });
+    }
+  },
+
+  /**
+   * Get the viewport dimensions
+   * @returns {Object} Object with width and height
+   */
+  getViewport: function() {
+    return {
+      width: window.innerWidth || document.documentElement.clientWidth,
+      height: window.innerHeight || document.documentElement.clientHeight
+    };
+  },
+
+  /**
+   * Check if element is in viewport
+   * @param {Element|string} element - Element or selector
+   * @param {number} threshold - Visibility threshold (0-1, default: 0)
+   * @returns {boolean} True if element is in viewport
+   */
+  isInViewport: function(element, threshold = 0) {
+    const el = typeof element === 'string' ? document.querySelector(element) : element;
+    if (!el) return false;
+
+    const rect = el.getBoundingClientRect();
+    const viewport = this.getViewport();
+
+    return (
+      rect.top >= -threshold * rect.height &&
+      rect.left >= -threshold * rect.width &&
+      rect.bottom <= viewport.height + threshold * rect.height &&
+      rect.right <= viewport.width + threshold * rect.width
+    );
+  },
+
+  /**
+   * Scroll element into view
+   * @param {Element|string} element - Element or selector
+   * @param {Object} options - ScrollIntoView options
+   */
+  scrollIntoView: function(element, options = { behavior: 'smooth', block: 'center' }) {
+    const el = typeof element === 'string' ? document.querySelector(element) : element;
+    if (el) el.scrollIntoView(options);
+  }
+};
+

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@briannorman9/eli-utils",
+  "version": "1.0.0",
+  "description": "Utility functions for ELI web experiments",
+  "main": "index.js",
+  "type": "module",
+  "exports": {
+    ".": "./index.js"
+  },
+  "keywords": [
+    "eli",
+    "utils",
+    "web-experiments",
+    "utilities"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=12.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/briannorman/eli.git",
+    "directory": "packages/eli-utils"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}
+