powerpagestoolkit 2.6.3 → 2.6.3201

package/README.md

@@ -27,31 +27,88 @@ A powerful class for managing DOM elements with automatic value synchronization
 
 #### Basic Usage
 
-DOMNodeReferences are instantiated with the help of the following factory function
+DOMNodeReferences are instantiated with the help of the following factory function: `createRef`
 
 ```typescript
 createRef(
-  target: HTMLElement | string, /* You can target an HTMLElement directly,
-  or use standard querySelector syntax */
-  multiple: (() => boolean) | boolean = false /* are you targeting a single
-  element, or multiple? true = multiple. Default is false (single) */
+  target: HTMLElement | string,
+  options: {
+    multiple: (() => boolean) | boolean = false,
+    root: HTMLElement,
+    timeout: number
+  }
 ): Promise<DOMNodeReference | DOMNodeReferenceArray>;
 ```
 
+createRef takes two main arguments:
+
+<table style="width: 100%; border-collapse: collapse;">
+  <thead>
+    <tr>
+      <th style="border: 1px solid #ddd; padding: 8px; text-align: left;">Property</th>
+      <th style="border: 1px solid #ddd; padding: 8px; text-align: left;">Type</th>
+      <th style="border: 1px solid #ddd; padding: 8px; text-align: left;">Details</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td style="border: 1px solid #ddd; padding: 8px;">target</td>
+      <td style="border: 1px solid #ddd; padding: 8px;">
+        <pre><code class="language-javascript">string | HTMLElement</code></pre>
+      </td>
+      <td style="border: 1px solid #ddd; padding: 8px;">
+        Use standard <code>querySelector</code> syntax to target an element, or elements in the DOM, or pass in an instance of the element itself to create a reference.
+      </td>
+    </tr>
+    <tr>
+      <td style="border: 1px solid #ddd; padding: 8px;">options</td>
+      <td style="border: 1px solid #ddd; padding: 8px;">
+        <pre><code class="language-javascript">{
+  multiple: () => boolean | boolean,
+  root: HTMLElement,
+  timeout: number
+}</code></pre>
+      </td>
+      <td style="border: 1px solid #ddd; padding: 8px;">
+        Provides advanced configurations for niche scenarios, such as async DOM element loading, returning arrays of elements, or specifying the parent to search within for the target node.
+      </td>
+    </tr>
+  </tbody>
+</table>
+
 Import the utility function for creating DOMNodeReference(s)
 
 ```typescript
 import { createRef } from "powerpagestoolkit";
 ```
 
-Instantiate one, or multiple instances of a DOMNodeReference
+Instantiate one, or multiple instances of a DOMNodeReference, and optionally configure advanced options
 
-```typescript
+```javascript
 // Create a single reference
-const node = await createRef("#myElement", false);
+const node = await createRef("#myElement");
 
 // Create multiple references
-const nodes = await createRef(".my-class", true);
+const nodes = await createRef(".my-class", { multiple: true });
+
+/******************/
+// ADVANCED OPTIONS
+// in the event that you need to be more granular with how you are targeting
+// and retrieving elements, there are additional options
+// If the node you are targeted is not available at the initial execution
+// of the script, set a timeout for 2 seconds
+const node2 = await createRef("#target", { timeout: 2000 });
+
+// need to target a node within a specific node? use that node as the root
+const otherElement = document.getElementById("id");
+const node3 = await createRef("#target", { root: otherElement });
+
+// implement all options:
+const nodes2 = await createRef("#target", {
+  multiple: true,
+  timeout: 4000,
+  root: otherElement,
+});
 ```
 
 #### Properties

package/dist/DOMNodeReference.d.ts

@@ -7,12 +7,16 @@ declare const _updateRadioGroup: unique symbol;
 declare const _attachVisibilityController: unique symbol;
 declare const _attachRadioButtons: unique symbol;
 declare const _bindMethods: unique symbol;
+declare const observers: unique symbol;
+declare const boundEventListeners: unique symbol;
 export default class DOMNodeReference {
     target: HTMLElement | string;
+    root: HTMLElement;
+    private debounceTime;
     private isLoaded;
     private defaultDisplay;
-    private observers;
-    private boundEventListeners;
+    private [observers];
+    private [boundEventListeners];
     /**
      * The value of the element that this node represents
      * stays in syncs with the live DOM elements?.,m  via event handler
@@ -41,8 +45,10 @@ export default class DOMNodeReference {
     /**
      * Creates an instance of DOMNodeReference.
      * @param target - The CSS selector to find the desired DOM element.
+     * @param root - Optionally specify the element within to search for the element targeted by 'target'
+     * Defaults to 'document.body'
      */
-    /******/ /******/ constructor(target: HTMLElement | string);
+    /******/ /******/ constructor(target: HTMLElement | string, root?: HTMLElement, debounceTime?: number);
     [_init](): Promise<void>;
     /**
      * Initializes value synchronization with appropriate event listeners

package/dist/bundle.js

@@ -103,35 +103,77 @@ var API = {
 var API_default = API;
 
 // src/waitFor.ts
-function waitFor(target, root = document) {
+function waitFor(target, root = document, multiple = false, debounceTime) {
   return new Promise((resolve, reject) => {
-    const observer = new MutationObserver(() => {
-      const observedElement = root.querySelector(target);
-      if (observedElement) {
+    if (multiple) {
+      let timeout;
+      const observedElements = [];
+      const observedSet = /* @__PURE__ */ new Set();
+      if (debounceTime < 1) {
+        return resolve(
+          Array.from(root.querySelectorAll(target))
+        );
+      }
+      const observer = new MutationObserver(() => {
+        const found = Array.from(root.querySelectorAll(target));
+        found.forEach((element) => {
+          if (!observedSet.has(element)) {
+            observedSet.add(element);
+            observedElements.push(element);
+          }
+        });
         clearTimeout(timeout);
+        timeout = setTimeout(() => {
+          if (observedElements.length > 0) {
+            observer.disconnect();
+            resolve(observedElements);
+          } else {
+            reject(
+              new Error(
+                `No elements found with target: "${target}" within ${debounceTime / 1e3} seconds. If the element you are expected has not loading, consider raising your timeout.`
+              )
+            );
+          }
+        }, debounceTime);
+      });
+      observer.observe(root, {
+        childList: true,
+        subtree: true,
+        attributes: false
+      });
+    } else {
+      const observer = new MutationObserver(() => {
+        const observedElement = root.querySelector(target);
+        if (observedElement) {
+          clearTimeout(timeout);
+          observer.disconnect();
+          resolve(observedElement);
+        }
+      });
+      const timeout = setTimeout(() => {
         observer.disconnect();
-        resolve(observedElement);
+        reject(
+          new Error(
+            `Element not found by target: "${target}" within ${debounceTime / 1e3} second. If the element you are expected has not loading, consider raising your timeout.`
+          )
+        );
+      }, debounceTime);
+      if (target instanceof HTMLElement) {
+        clearTimeout(timeout);
+        return resolve(target);
       }
-    });
-    const timeout = setTimeout(() => {
-      observer.disconnect();
-      reject(new Error(`Element not found: ${target} within 5 seconds`));
-    }, 5e3);
-    if (target instanceof HTMLElement) {
-      clearTimeout(timeout);
-      return resolve(target);
-    }
-    const element = root.querySelector(target);
-    if (element) {
-      clearTimeout(timeout);
-      return resolve(element);
+      const element = root.querySelector(target);
+      if (element) {
+        clearTimeout(timeout);
+        return resolve(element);
+      }
+      observer.observe(root, {
+        subtree: true,
+        attributes: true,
+        childList: true
+        // Detects added/removed child elements
+      });
     }
-    observer.observe(document.body, {
-      subtree: true,
-      attributes: true,
-      childList: true
-      // Detects added/removed child elements
-    });
   });
 }
 
@@ -237,13 +279,17 @@ var _updateRadioGroup = Symbol("_URG");
 var _attachVisibilityController = Symbol("_AVC");
 var _attachRadioButtons = Symbol("_ARB");
 var _bindMethods = Symbol("_B");
+var observers = Symbol("O");
+var boundEventListeners = Symbol("BEV");
 var DOMNodeReference = class _DOMNodeReference {
   // properties initialized in the constructor
   target;
+  root;
+  debounceTime;
   isLoaded;
   defaultDisplay;
-  observers = [];
-  boundEventListeners = [];
+  [observers] = [];
+  [boundEventListeners] = [];
   /**
    * The value of the element that this node represents
    * stays in syncs with the live DOM elements?.,m  via event handler
@@ -252,11 +298,15 @@ var DOMNodeReference = class _DOMNodeReference {
   /**
    * Creates an instance of DOMNodeReference.
    * @param target - The CSS selector to find the desired DOM element.
+   * @param root - Optionally specify the element within to search for the element targeted by 'target'
+   * Defaults to 'document.body'
    */
   /******/
   /******/
-  constructor(target) {
+  constructor(target, root = document.body, debounceTime = 5e3) {
     this.target = target;
+    this.root = root;
+    this.debounceTime = debounceTime;
     this.isLoaded = false;
     this.defaultDisplay = "";
     this.value = null;
@@ -264,8 +314,11 @@ var DOMNodeReference = class _DOMNodeReference {
   }
   async [_init]() {
     try {
-      const element = await waitFor(this.target);
-      this.element = element;
+      if (this.target instanceof HTMLElement) {
+        this.element = this.target;
+      } else {
+        this.element = await waitFor(this.target, this.root, false, this.debounceTime);
+      }
       if (!this.element) {
         throw new DOMNodeNotFoundError(this);
       }
@@ -323,7 +376,7 @@ var DOMNodeReference = class _DOMNodeReference {
       this.element.addEventListener(eventType, this.updateValue);
       const _element = this.element;
       const _updateValue = this.updateValue;
-      this.boundEventListeners.push({
+      this[boundEventListeners].push({
         element: _element,
         handler: _updateValue,
         event: eventType
@@ -343,10 +396,10 @@ var DOMNodeReference = class _DOMNodeReference {
     if (!parentElement) {
       throw new Error("Date input must have a parent element");
     }
-    const dateNode = await waitFor("[data-date-format]", parentElement);
+    const dateNode = await waitFor("[data-date-format]", parentElement, false, 1500);
     dateNode.addEventListener("select", this.updateValue);
     const _handler = this.updateValue;
-    this.boundEventListeners.push({
+    this[boundEventListeners].push({
       element: dateNode,
       handler: _handler,
       event: "select"
@@ -435,10 +488,10 @@ var DOMNodeReference = class _DOMNodeReference {
     }
   }
   [_destroy]() {
-    this.boundEventListeners?.forEach((binding) => {
+    this[boundEventListeners]?.forEach((binding) => {
       binding.element?.removeEventListener(binding.event, binding.handler);
     });
-    this.observers?.forEach((observer) => {
+    this[observers]?.forEach((observer) => {
       observer.disconnect();
     });
     this.yesRadio?.[_destroy]();
@@ -477,7 +530,7 @@ var DOMNodeReference = class _DOMNodeReference {
     this.element.addEventListener(eventType, eventHandler.bind(this));
     const _element = this.element;
     const _handler = eventHandler;
-    this.boundEventListeners.push({
+    this[boundEventListeners].push({
       element: _element,
       handler: _handler,
       event: eventType
@@ -596,7 +649,7 @@ var DOMNodeReference = class _DOMNodeReference {
         );
         if (childInputs.length > 0) {
           const promises = childInputs.map(async (input) => {
-            const inputRef = await createDOMNodeReference(input, false);
+            const inputRef = await createDOMNodeReference(input, { multiple: false });
             return inputRef.clearValue();
           });
           await Promise.all(promises);
@@ -880,14 +933,14 @@ var DOMNodeReference = class _DOMNodeReference {
         }
       };
       dep.on("change", handleChange);
-      this.boundEventListeners.push({
+      this[boundEventListeners].push({
         element: dep.element,
         event: "change",
         handler: handleChange
       });
       if (trackInputEvents) {
         dep.on("input", handleChange);
-        this.boundEventListeners.push({
+        this[boundEventListeners].push({
           element: dep.element,
           event: "input",
           handler: handleChange
@@ -907,12 +960,12 @@ var DOMNodeReference = class _DOMNodeReference {
           attributeFilter: ["style"],
           subtree: false
         });
-        this.observers.push(observer);
+        this[observers].push(observer);
       }
       if (trackRadioButtons && dep.yesRadio && dep.noRadio) {
         [dep.yesRadio, dep.noRadio].forEach((radio) => {
           radio.on("change", handleChange);
-          this.boundEventListeners.push({
+          this[boundEventListeners].push({
             element: radio.element,
             event: "change",
             handler: handleChange
@@ -964,12 +1017,17 @@ var DOMNodeReference = class _DOMNodeReference {
       subtree: true,
       childList: true
     });
-    this.observers.push(observer);
+    this[observers].push(observer);
   }
 };
 
 // src/createDOMNodeReferences.ts
-async function createDOMNodeReference(target, multiple = false) {
+async function createDOMNodeReference(target, options = {
+  multiple: false,
+  root: document.body,
+  timeout: 0
+}) {
+  const { multiple = false, root = document.body, timeout = 0 } = options;
   try {
     const isMultiple = typeof multiple === "function" ? multiple() : multiple;
     if (isMultiple) {
@@ -978,9 +1036,7 @@ async function createDOMNodeReference(target, multiple = false) {
           `'target' must be of type 'string' if 'multiple' is set to 'true'. Received type: '${typeof target}'`
         );
       }
-      const elements = Array.from(
-        document.querySelectorAll(target)
-      );
+      const elements = await waitFor(target, root, true, timeout);
       const initializedElements = await Promise.all(
         elements.map(async (element) => {
           const instance2 = new DOMNodeReference(element);
@@ -990,7 +1046,7 @@ async function createDOMNodeReference(target, multiple = false) {
       );
       return enhanceArray(initializedElements);
     }
-    const instance = new DOMNodeReference(target);
+    const instance = new DOMNodeReference(target, root, timeout);
     await instance[_init]();
     return new Proxy(instance, createProxyHandler());
   } catch (e) {

package/dist/createDOMNodeReferences.d.ts

@@ -1,9 +1,7 @@
 import DOMNodeReference from "./DOMNodeReference.js";
-/**
- * Creates and initializes a DOMNodeReference instance.
- * @async
- * @param  target - The CSS selector for the desired DOM element, or, optionally, the element itself for which to create a DOMNodeReference.
- * @param multiple Should this call return an array of instantiated references, or just a single? Defaults to false, returning a single instance
- * @returns  A promise that resolves to a Proxy of the initialized DOMNodeReference instance.
- */
-export default function createDOMNodeReference(target: HTMLElement | string, multiple?: (() => boolean) | boolean): Promise<DOMNodeReference | DOMNodeReference[]>;
+export default function createDOMNodeReference(target: HTMLElement | string, options?: {
+    multiple?: false | undefined;
+}): Promise<DOMNodeReference>;
+export default function createDOMNodeReference(target: HTMLElement | string, options?: {
+    multiple?: true;
+}): Promise<DOMNodeReference[]>;

package/dist/waitFor.d.ts

@@ -1,7 +1,2 @@
-/**
- *
- * @param target basic querySelector syntax to select an element
- * @param root optional parameter to replace document as the root from which to perform the node search
- * @returns
- */
-export default function waitFor(target: HTMLElement | string, root?: HTMLElement | Document): Promise<HTMLElement>;
+export default function waitFor(target: HTMLElement | string, root: HTMLElement | Document, multiple: false, debounceTime: number): Promise<HTMLElement>;
+export default function waitFor(target: HTMLElement | string, root: HTMLElement | Document, multiple: true, debounceTime: number): Promise<HTMLElement[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "powerpagestoolkit",
-  "version": "2.6.03",
+  "version": "2.6.3201",
   "description": "Reference, manipulate, and engage with Power Pages sites through the nodes in the DOM; use a variety of custom methods that allow customizing your power pages site quicker and easier.  ",
   "main": "./dist/bundle.js",
   "types": "./dist/index.d.ts",