@briannorman9/eli-utils 1.0.0 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Brian Norman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,6 @@
 # @briannorman9/eli-utils
 
-Utility functions for ELI web experiments.
+Utility functions for web experiments with ELI (Experimentation Local Interface).
 
 ## Installation
 
@@ -10,72 +10,214 @@ 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):
+Import the utils in your ELI variant code:
 
 ```javascript
 import utils from '@eli/utils';
+```
+
+**Note:** ELI's import system automatically resolves `@eli/utils` to `@briannorman9/eli-utils` from your project's `node_modules`.
+
+## API
 
-// Wait for an element to appear
+### DOM Utilities
+
+#### `waitForElement(selector)`
+Wait for the first element matching the selector to appear in the DOM. Note: This only matches the first element. Use `waitForElements()` to match all elements.
+
+```javascript
 utils.waitForElement('#myElement').then(element => {
   console.log('Element found:', element);
 });
+```
+
+#### `waitForElements(selector, context)`
+Wait for all elements matching the selector to appear in the DOM. Note: This matches all elements. Use `waitForElement()` to match only the first element.
+
+```javascript
+utils.waitForElements('.product-card').then(elements => {
+  elements.forEach(card => card.style.border = '2px solid red');
+});
+```
+
+#### `waitUntil(condition, interval)`
+Wait until a condition function returns true.
 
-// Wait until a condition is met
+```javascript
 utils.waitUntil(() => document.readyState === 'complete');
+```
+
+#### `select(selector, context)`
+Select a single element (returns immediately, does not wait).
 
-// DOM manipulation
+```javascript
+const button = utils.select('#myButton');
+```
+
+#### `observeSelector(selector, callback, options)`
+Observe mutations on the first element matching the selector. The callback is called every time the element is mutated (attributes, children, text, etc.). Note: This only observes the first matching element. Use `observeSelectors()` to observe all elements.
+
+**Mutation types:**
+- `'childList'` - Watch for child nodes being added/removed (default: true)
+- `'attributes'` - Watch for attribute changes (default: true)
+- `'characterData'` - Watch for text content changes (default: false)
+- `'subtree'` - Watch all descendants, not just direct children (default: true)
+- `'attributeOldValue'` - Include old attribute value in mutation record (default: false)
+- `'characterDataOldValue'` - Include old text value in mutation record (default: false)
+- `'attributeFilter'` - Array of attribute names to observe (only these attributes will trigger)
+
+```javascript
+// Observe attribute changes on a button
+const stopObserving = utils.observeSelector('#myButton', (element, mutation) => {
+  console.log('Button mutated:', mutation.type);
+  if (mutation.type === 'attributes') {
+    console.log('Attribute changed:', mutation.attributeName);
+  }
+}, {
+  mutations: ['attributes'],
+  attributeFilter: ['class', 'disabled']
+});
+
+// Observe when children are added/removed
+utils.observeSelector('.product-list', (element, mutation) => {
+  if (mutation.type === 'childList') {
+    console.log('Children changed:', mutation.addedNodes.length, 'added');
+  }
+}, {
+  mutations: ['childList', 'subtree']
+});
+```
+
+#### `observeSelectors(selector, callback, options)`
+Observe mutations on all elements matching the selector. The callback is called every time any matching element is mutated. Note: This observes all matching elements. Use `observeSelector()` to observe only the first element.
+
+```javascript
+// Observe all product cards for attribute changes
+const stopObserving = utils.observeSelectors('.product-card', (element, mutation) => {
+  if (mutation.type === 'attributes' && mutation.attributeName === 'data-price') {
+    console.log('Price changed on:', element);
+  }
+}, {
+  mutations: ['attributes'],
+  attributeFilter: ['data-price', 'class']
+});
+```
+
+### Class Manipulation
+
+#### `addClass(element, className)`
+Add a class to an element.
+
+```javascript
 utils.addClass('#myButton', 'active');
+```
+
+#### `removeClass(element, className)`
+Remove a class from an element.
+
+```javascript
 utils.removeClass('#myButton', 'inactive');
+```
+
+#### `toggleClass(element, className)`
+Toggle a class on an element.
+
+```javascript
+utils.toggleClass('#myButton', 'active');
+```
+
+#### `hasClass(element, className)`
+Check if an element has a class.
+
+```javascript
+if (utils.hasClass('#myButton', 'active')) {
+  console.log('Button is active');
+}
+```
+
+### Event Handling
 
-// Event handling
+#### `on(element, event, handler)`
+Add an event listener.
+
+```javascript
 utils.on('#myButton', 'click', () => console.log('Clicked!'));
+```
 
-// Cookies
-const userId = utils.getCookie('userId');
-utils.setCookie('userId', '12345', 30);
+#### `off(element, event, handler)`
+Remove an event listener.
 
-// Query parameters
-const campaign = utils.getQueryParam('campaign');
+```javascript
+utils.off('#myButton', 'click', handler);
+```
 
-// Custom events
-utils.triggerEvent('experimentLoaded', { variant: 'v1' });
+#### `delegate(parent, selector, event, handler)`
+Event delegation - attach event to parent, handle on children.
+
+```javascript
+utils.delegate('#container', '.button', 'click', (e) => {
+  console.log('Button clicked:', e.target);
+});
 ```
 
-## API Reference
+#### `triggerEvent(eventName, data, target)`
+Trigger a custom event.
 
-### Element Utilities
+```javascript
+utils.triggerEvent('experimentLoaded', { variant: 'v1' });
+```
 
-- `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
+### Cookies
 
-### Event Utilities
+#### `getCookie(name)`
+Get a cookie value by name.
 
-- `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
+```javascript
+const userId = utils.getCookie('userId');
+```
 
-### Cookie Utilities
+#### `setCookie(name, value, days, path)`
+Set a cookie.
 
-- `getCookie(name)` - Get cookie value
-- `setCookie(name, value, days, path)` - Set cookie
+```javascript
+utils.setCookie('userId', '12345', 30);
+```
 
 ### URL Utilities
 
-- `getQueryParam(name, url)` - Get URL query parameter
+#### `getQueryParam(name, url)`
+Get a URL query parameter value.
+
+```javascript
+const campaign = utils.getQueryParam('campaign');
+```
 
 ### Viewport Utilities
 
-- `getViewport()` - Get viewport dimensions
-- `isInViewport(element, threshold)` - Check if element is in viewport
-- `scrollIntoView(element, options)` - Scroll element into view
+#### `getViewport()`
+Get the viewport dimensions.
+
+```javascript
+const { width, height } = utils.getViewport();
+```
+
+#### `isInViewport(element, threshold)`
+Check if element is in viewport.
+
+```javascript
+if (utils.isInViewport('#myElement')) {
+  console.log('Element is visible');
+}
+```
+
+#### `scrollIntoView(element, options)`
+Scroll element into view.
+
+```javascript
+utils.scrollIntoView('#myElement', { behavior: 'smooth', block: 'center' });
+```
 
 ## License
 
 MIT
+