powerpagestoolkit 2.6.2 → 2.6.4

package/README.md

@@ -27,31 +27,89 @@ 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) */
-): Promise<DOMNodeReference | DOMNodeReferenceArray>;
+  target: HTMLElement | string,
+  options: {
+    multiple: (() => boolean) | boolean = false,
+    root: HTMLElement,
+    timeout: number
+  }
+): Promise<DOMNodeReference | DOMNodeReference[]>;
 ```
 
+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 targeting 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
@@ -101,7 +159,7 @@ _Method signature:_
 ```typescript
 configureConditionalRendering(
     condition: () => boolean,
-    dependencies?: Array<DOMNodeReference>,
+    dependencies?: DOMNodeReference[],
     clearValuesOnHide: boolean = true
   ): DOMNodeReference /* Instance of this returned
   for optional method chaining */
@@ -159,9 +217,9 @@ node.configureValidationAndRequirements(
 
 ##### Element Manipulation
 
-```typescript
-/****/ Value management /****/
+_Value management_
 
+```typescript
 // set a static value
 node.setValue("new value");
 
@@ -176,25 +234,31 @@ node.setValue(() => {
 node.updateValue();
 
 // Clear the value for both the instance and the target element
-node.clearValue()
+node.clearValue();
+```
 
-/****/ Content manipulation /****/
+_Content manipulation_
 
+```typescript
 node.setInnerHTML("<span>New content</span>");
 node.append(childElement);
 node.prepend(headerElement);
 node.after(siblingElement);
 node.before(labelElement);
+```
 
-/****/ Styling /****/
+_Styling_
 
+```typescript
 node.setStyle({
   display: "block",
   color: "red",
 });
+```
 
-/****/ State management /****/
+_Enabling/Disabling inputs_
 
+```typescript
 node.disable();
 node.enable();
 

package/dist/API.d.ts

@@ -12,7 +12,7 @@ declare const API: {
      * @param selectColumns *OPTIONAL* if desired, enter your own custom OData query for advanced GET results. Format = select=column1,column2,column3...
      * @returns a Promise resolving the successful results of the GET request, or rejecting the failed results of the GET request
      */
-    getRecord(tableSetName: string, recordID: string, selectColumns?: string): Promise<object>;
+    getRecord<T>(tableSetName: string, recordID: string, selectColumns?: string): Promise<T>;
     /**
      *
      * @param tableSetName The dataverse set name of the table being queried

package/dist/DOMNodeReference.d.ts

@@ -1,3 +1,45 @@
+interface BusinessRule {
+    /**
+     * @param condition A function that returns a boolean to determine
+     * the visibility of the target element. If `condition()` returns true, the element is shown;
+     * otherwise, it is hidden.
+     * @param dependencies An array of `DOMNodeReference` instances. Event listeners are
+     * registered on each to toggle the visibility of the target element based on the `condition` and the visibility of
+     * the target node.
+     * @param clearValuesOnHide Should the values in the targeted field be cleared when hidden? Defaults to true
+     */
+    setVisibility?: [
+        condition: () => boolean,
+        dependencies: DOMNodeReference[],
+        clearValuesOnHide?: boolean
+    ];
+    /**
+     * @param isRequired Function determining if field is required
+     * @param isValid Function validating field input
+     * @param fieldDisplayName Display name for error messages
+     * @param dependencies Fields that trigger requirement/validation updates
+     */
+    setRequired?: [
+        isRequired: () => boolean,
+        isValid: () => boolean,
+        fieldDisplayName: string,
+        dependencies: DOMNodeReference[]
+    ];
+    /**
+     * @param condition A function to determine the value of this
+     * element, given applied logic
+     * @param value The value to set for the HTML element.
+     * for parents of boolean radios, pass true or false as value, or
+     * an expression returning a boolean
+     */
+    setValue?: [condition: () => boolean, value: any];
+    /**
+     * @param condition A function to determine if this field
+     * should be enabled in a form, or disabled. True || 1 = disabled. False || 0 = enabled
+     * @param dependencies
+     */
+    setDisabled?: [condition: () => boolean, dependencies: DOMNodeReference[]];
+}
 export declare const _init: unique symbol;
 declare const _destroy: unique symbol;
 declare const _valueSync: unique symbol;
@@ -7,12 +49,17 @@ declare const _updateRadioGroup: unique symbol;
 declare const _attachVisibilityController: unique symbol;
 declare const _attachRadioButtons: unique symbol;
 declare const _bindMethods: unique symbol;
+declare const _debounceTime: unique symbol;
+declare const _observers: unique symbol;
+declare const _boundEventListeners: unique symbol;
 export default class DOMNodeReference {
-    target: HTMLElement | string;
+    target: Element | string;
+    root: Element;
+    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 +88,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: Element | string, root: Element | undefined, debounceTime: number);
     [_init](): Promise<void>;
     /**
      * Initializes value synchronization with appropriate event listeners
@@ -180,7 +229,7 @@ export default class DOMNodeReference {
     remove(): this;
     /**
      *
-     * @param {Partial<CSSStyleDeclaration} options and object containing the styles you want to set : {key: value} e.g.: {'display': 'block'}
+     * @param options and object containing the styles you want to set : {key: value} e.g.: {'display': 'block'}
      * @returns - Instance of this [provides option to method chain]
      */
     setStyle(options: Partial<CSSStyleDeclaration>): this;
@@ -189,52 +238,59 @@ export default class DOMNodeReference {
      * @returns - Instance of this [provides option to method chain]
      */
     uncheckRadios(): DOMNodeReference;
+    /**
+     * Applies a business rule to manage visibility, required state, value, and disabled state dynamically.
+     *
+     * @param rule The business rule containing conditions for various actions.
+     * @returns Instance of this for method chaining.
+     */
+    applyBusinessRule(rule: Partial<BusinessRule>): DOMNodeReference;
     /**
      * Configures conditional rendering for the target element based on a condition
      * and the visibility of one or more trigger elements.
-     *
-     * @param condition - A function that returns a boolean to determine
+     * @deprecated Use the new 'applyBusinessRule Method
+     * @param condition A function that returns a boolean to determine
      * the visibility of the target element. If `condition()` returns true, the element is shown;
      * otherwise, it is hidden.
      * @param dependencies - An array of `DOMNodeReference` instances. Event listeners are
      * registered on each to toggle the visibility of the target element based on the `condition` and the visibility of
      * the target node.
-     * @throws - When there's an error in setting up conditional rendering
-     * @returns - Instance of this [provides option to method chain]
+     * @throws When there's an error in setting up conditional rendering
+     * @returns Instance of this [provides option to method chain]
      */
     configureConditionalRendering(condition: () => boolean, dependencies?: Array<DOMNodeReference>, clearValuesOnHide?: boolean): DOMNodeReference;
     /**
      * Sets up validation and requirement rules for the field with enhanced error handling and dynamic updates.
-     *
-     * @param isRequired - Function determining if field is required
-     * @param isValid - Function validating field input
-     * @param fieldDisplayName - Display name for error messages
-     * @param dependencies - Fields that trigger requirement/validation updates
-     * @returns - Instance of this
-     * @throws - If validation setup fails
+     * @deprecated Use the new 'applyBusinessRule Method
+     * @param isRequired Function determining if field is required
+     * @param isValid Function validating field input
+     * @param fieldDisplayName Display name for error messages
+     * @param dependencies Fields that trigger requirement/validation updates
+     * @returns Instance of this
+     * @throws If validation setup fails
      */
     configureValidationAndRequirements(isRequired: () => boolean, isValid: () => boolean, fieldDisplayName: string, dependencies: Array<DOMNodeReference>): DOMNodeReference;
     /**
      * Sets up tracking for dependencies using both event listeners and mutation observers.
      * @private
-     * @param handler - The function to execute when dependencies change
-     * @param dependencies - Array of dependent DOM nodes to track
-     * @param options - Additional configuration options
+     * @param handler The function to execute when dependencies change
+     * @param dependencies Array of dependent DOM nodes to track
+     * @param options Additional configuration options
      */
     private _configDependencyTracking;
     /**
      * Sets the required level for the field by adding or removing the "required-field" class on the label.
      *
-     * @param isRequired - Determines whether the field should be marked as required.
+     * @param isRequired Determines whether the field should be marked as required.
      * If true, the "required-field" class is added to the label; if false, it is removed.
-     * @returns - Instance of this [provides option to method chain]
+     * @returns Instance of this [provides option to method chain]
      */
     setRequiredLevel(isRequired: (() => boolean) | boolean): DOMNodeReference;
     /**
      * Executes a callback function once the element is fully loaded.
      * If the element is already loaded, the callback is called immediately.
      * Otherwise, a MutationObserver is used to detect when the element is added to the DOM.
-     * @param callback - A callback function to execute once the element is loaded.
+     * @param callback A callback function to execute once the element is loaded.
      * Receives instance of 'this' as an argument
      */
     onceLoaded(callback: (instance: DOMNodeReference) => any): any;

package/dist/DOMNodeReferenceArray.d.ts

@@ -0,0 +1,12 @@
+import DOMNodeReference from "./DOMNodeReference.js";
+export declare class DOMNodeReferenceArray extends Array<DOMNodeReference> {
+    /**
+     * Hides all the containers of the DOMNodeReference instances in the array.
+     */
+    hideAll(this: DOMNodeReferenceArray): DOMNodeReferenceArray;
+    /**
+     * Shows all the containers of the DOMNodeReference instances in the array.
+     */
+    showAll(this: DOMNodeReferenceArray): DOMNodeReferenceArray;
+}
+export declare function enhanceArray<T extends string>(array: DOMNodeReference[]): DOMNodeReferenceArray & Record<T, DOMNodeReference>;

package/dist/List.d.ts

@@ -20,6 +20,7 @@ interface ListOptions {
 interface ListItem extends Array<Element> {
 }
 export default class List {
+    [x: symbol]: () => Promise<List>;
     items: ListItem[];
     private options;
     private container;

package/dist/bindForm.d.ts

@@ -0,0 +1,11 @@
+import DOMNodeReference from "./DOMNodeReference.js";
+import { DOMNodeReferenceArray } from "./DOMNodeReferenceArray.js";
+/**
+ * @function
+ * Get all controls related to the form for manipulating with the
+ * DOMNodeReference class. Rather than having to instantiate each fields that you need manually,
+ * you can call this method once with the form ID and gain access to all fields
+ * @param formId The string GUID of the form you want to bind to
+ * @returns An array of DOMNodeReferences
+ */
+export default function bindForm<T extends string>(formId: string): Promise<DOMNodeReferenceArray & Record<T, DOMNodeReference>>;

package/dist/bundle.js

@@ -102,36 +102,110 @@ var API = {
 };
 var API_default = API;
 
+// src/DOMNodeReferenceArray.ts
+var DOMNodeReferenceArray = class extends Array {
+  /**
+   * Hides all the containers of the DOMNodeReference instances in the array.
+   */
+  hideAll() {
+    this.forEach((instance) => instance.hide());
+    return this;
+  }
+  /**
+   * Shows all the containers of the DOMNodeReference instances in the array.
+   */
+  showAll() {
+    this.forEach((instance) => instance.show());
+    return this;
+  }
+};
+function enhanceArray(array) {
+  const enhancedArray = new DOMNodeReferenceArray(...array);
+  return new Proxy(enhancedArray, {
+    get(target, prop, receiver) {
+      if (prop in target) {
+        return Reflect.get(target, prop, receiver);
+      }
+      if (typeof prop === "string") {
+        return target.find((instance) => instance.element.id === prop);
+      }
+      return void 0;
+    }
+  });
+}
+
 // 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 expecting has not loaded yet, 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 expecting has not loaded yet, 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 +311,18 @@ var _updateRadioGroup = Symbol("_URG");
 var _attachVisibilityController = Symbol("_AVC");
 var _attachRadioButtons = Symbol("_ARB");
 var _bindMethods = Symbol("_B");
+var _debounceTime = Symbol("DT");
+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 +331,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) {
     this.target = target;
+    this.root = root;
+    this[_debounceTime] = debounceTime;
     this.isLoaded = false;
     this.defaultDisplay = "";
     this.value = null;
@@ -264,8 +347,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);
       }
@@ -302,30 +388,28 @@ var DOMNodeReference = class _DOMNodeReference {
   async [_valueSync]() {
     try {
       this.updateValue();
-      if (!(this.element instanceof HTMLElement)) {
-        throw new Error("Element is not a valid HTML element");
-      }
       const eventMapping = {
         checkbox: "click",
         radio: "click",
         select: "change",
-        "select-multiple": "change"
+        "select-multiple": "change",
+        textarea: "keyup"
         // Add other input types as needed
       };
       let eventType;
       if (this.element instanceof HTMLSelectElement) {
         eventType = "change";
       } else if (this.element instanceof HTMLInputElement) {
-        eventType = eventMapping[this.element.type] || "input";
+        eventType = eventMapping[this.element.type] ?? "input";
+      } else if (this.element instanceof HTMLTextAreaElement) {
+        eventType = eventMapping[this.element.type] ?? "input";
       } else {
         eventType = "input";
       }
       this.element.addEventListener(eventType, this.updateValue);
-      const _element = this.element;
-      const _updateValue = this.updateValue;
-      this.boundEventListeners.push({
-        element: _element,
-        handler: _updateValue,
+      this[_boundEventListeners].push({
+        element: this.element,
+        handler: this.updateValue,
         event: eventType
       });
       if (this.element instanceof HTMLInputElement && this.element.dataset.type === "date") {
@@ -343,10 +427,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"
@@ -427,7 +511,8 @@ var DOMNodeReference = class _DOMNodeReference {
     this.noRadio = await createDOMNodeReference(`#${this.element.id}_0`);
   }
   [_bindMethods]() {
-    for (const key of Object.getOwnPropertyNames(Object.getPrototypeOf(this))) {
+    const prototype = Object.getPrototypeOf(this);
+    for (const key of Object.getOwnPropertyNames(prototype)) {
       const value = this[key];
       if (key !== "constructor" && typeof value === "function") {
         this[key] = value.bind(this);
@@ -435,10 +520,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 +562,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
@@ -525,7 +610,7 @@ var DOMNodeReference = class _DOMNodeReference {
     if (value instanceof Function) {
       value = value();
     }
-    if (this.element.classList.contains("boolean-radio")) {
+    if (this.element.classList.contains("boolean-radio") && this.yesRadio instanceof _DOMNodeReference && this.noRadio instanceof _DOMNodeReference) {
       this.yesRadio.element.checked = value;
       this.noRadio.element.checked = !value;
     } else {
@@ -596,7 +681,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);
@@ -716,7 +801,7 @@ var DOMNodeReference = class _DOMNodeReference {
   }
   /**
    *
-   * @param {Partial<CSSStyleDeclaration} options and object containing the styles you want to set : {key: value} e.g.: {'display': 'block'}
+   * @param options and object containing the styles you want to set : {key: value} e.g.: {'display': 'block'}
    * @returns - Instance of this [provides option to method chain]
    */
   setStyle(options) {
@@ -725,7 +810,8 @@ var DOMNodeReference = class _DOMNodeReference {
         `powerpagestoolkit: 'DOMNodeReference.setStyle' required options to be in the form of an object. Argument passed was of type: ${typeof options}`
       );
     }
-    for (const key in options) {
+    for (const _key in options) {
+      const key = _key;
       this.element.style[key] = options[key];
     }
     return this;
@@ -745,18 +831,106 @@ var DOMNodeReference = class _DOMNodeReference {
     }
     return this;
   }
+  /**
+   * Applies a business rule to manage visibility, required state, value, and disabled state dynamically.
+   *
+   * @param rule The business rule containing conditions for various actions.
+   * @returns Instance of this for method chaining.
+   */
+  applyBusinessRule(rule) {
+    try {
+      if (rule.setVisibility) {
+        const [condition, dependencies = [], clearValuesOnHide = true] = rule.setVisibility;
+        const initialState = condition();
+        this.toggleVisibility(initialState);
+        if (dependencies.length) {
+          this._configDependencyTracking(
+            () => this.toggleVisibility(condition()),
+            dependencies,
+            {
+              clearValuesOnHide,
+              observeVisibility: true,
+              trackInputEvents: false,
+              trackRadioButtons: false
+            }
+          );
+        }
+      }
+      if (rule.setRequired) {
+        const [isRequired, isValid, fieldDisplayName, dependencies] = rule.setRequired;
+        if (!fieldDisplayName.trim()) {
+          throw new ValidationConfigError(
+            this,
+            "Field display name is required"
+          );
+        }
+        if (typeof Page_Validators === "undefined") {
+          throw new ValidationConfigError(this, "Page_Validators not found");
+        }
+        const validatorId = `${this.element.id}Validator`;
+        const newValidator = document.createElement("span");
+        newValidator.style.display = "none";
+        newValidator.id = validatorId;
+        Object.assign(newValidator, {
+          controltovalidate: this.element.id,
+          errormessage: `<a href='#${this.element.id}_label'>${fieldDisplayName} is a required field</a>`,
+          evaluationfunction: () => {
+            const isFieldRequired = isRequired();
+            const isFieldVisible = window.getComputedStyle(this.visibilityController).display !== "none";
+            return !isFieldRequired || !isFieldVisible || isValid();
+          }
+        });
+        Page_Validators.push(newValidator);
+        this.setRequiredLevel(isRequired());
+        this._configDependencyTracking(
+          () => this.setRequiredLevel(isRequired()),
+          dependencies
+        );
+      }
+      if (rule.setValue) {
+        const [condition, value] = rule.setValue;
+        if (condition()) {
+          this.setValue(value);
+        }
+      }
+      if (rule.setDisabled) {
+        const [condition, dependencies = []] = rule.setDisabled;
+        condition() ? this.disable() : this.enable();
+        const initialState = condition();
+        if (dependencies.length) {
+          this._configDependencyTracking(
+            () => {
+              condition() ? this.enable() : this.disable();
+            },
+            dependencies,
+            {
+              observeVisibility: true,
+              trackInputEvents: true,
+              trackRadioButtons: true
+            }
+          );
+        }
+      }
+      return this;
+    } catch (error) {
+      throw new ValidationConfigError(
+        this,
+        `Failed to apply business rule: ${error}`
+      );
+    }
+  }
   /**
    * Configures conditional rendering for the target element based on a condition
    * and the visibility of one or more trigger elements.
-   *
-   * @param condition - A function that returns a boolean to determine
+   * @deprecated Use the new 'applyBusinessRule Method
+   * @param condition A function that returns a boolean to determine
    * the visibility of the target element. If `condition()` returns true, the element is shown;
    * otherwise, it is hidden.
    * @param dependencies - An array of `DOMNodeReference` instances. Event listeners are
    * registered on each to toggle the visibility of the target element based on the `condition` and the visibility of
    * the target node.
-   * @throws - When there's an error in setting up conditional rendering
-   * @returns - Instance of this [provides option to method chain]
+   * @throws When there's an error in setting up conditional rendering
+   * @returns Instance of this [provides option to method chain]
    */
   configureConditionalRendering(condition, dependencies, clearValuesOnHide = true) {
     try {
@@ -790,13 +964,13 @@ var DOMNodeReference = class _DOMNodeReference {
   }
   /**
    * Sets up validation and requirement rules for the field with enhanced error handling and dynamic updates.
-   *
-   * @param isRequired - Function determining if field is required
-   * @param isValid - Function validating field input
-   * @param fieldDisplayName - Display name for error messages
-   * @param dependencies - Fields that trigger requirement/validation updates
-   * @returns - Instance of this
-   * @throws - If validation setup fails
+   * @deprecated Use the new 'applyBusinessRule Method
+   * @param isRequired Function determining if field is required
+   * @param isValid Function validating field input
+   * @param fieldDisplayName Display name for error messages
+   * @param dependencies Fields that trigger requirement/validation updates
+   * @returns Instance of this
+   * @throws If validation setup fails
    */
   configureValidationAndRequirements(isRequired, isValid, fieldDisplayName, dependencies) {
     if (!fieldDisplayName?.trim()) {
@@ -845,9 +1019,9 @@ var DOMNodeReference = class _DOMNodeReference {
   /**
    * Sets up tracking for dependencies using both event listeners and mutation observers.
    * @private
-   * @param handler - The function to execute when dependencies change
-   * @param dependencies - Array of dependent DOM nodes to track
-   * @param options - Additional configuration options
+   * @param handler The function to execute when dependencies change
+   * @param dependencies Array of dependent DOM nodes to track
+   * @param options Additional configuration options
    */
   _configDependencyTracking(handler, dependencies, options = {
     clearValuesOnHide: false,
@@ -880,14 +1054,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 +1081,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
@@ -924,9 +1098,9 @@ var DOMNodeReference = class _DOMNodeReference {
   /**
    * Sets the required level for the field by adding or removing the "required-field" class on the label.
    *
-   * @param isRequired - Determines whether the field should be marked as required.
+   * @param isRequired Determines whether the field should be marked as required.
    * If true, the "required-field" class is added to the label; if false, it is removed.
-   * @returns - Instance of this [provides option to method chain]
+   * @returns Instance of this [provides option to method chain]
    */
   setRequiredLevel(isRequired) {
     if (isRequired instanceof Function) {
@@ -941,7 +1115,7 @@ var DOMNodeReference = class _DOMNodeReference {
    * Executes a callback function once the element is fully loaded.
    * If the element is already loaded, the callback is called immediately.
    * Otherwise, a MutationObserver is used to detect when the element is added to the DOM.
-   * @param callback - A callback function to execute once the element is loaded.
+   * @param callback A callback function to execute once the element is loaded.
    * Receives instance of 'this' as an argument
    */
   onceLoaded(callback) {
@@ -964,13 +1138,24 @@ 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
+}) {
   try {
+    if (typeof options !== "object") {
+      throw new Error(
+        `'options' must be of type 'object'. Received type: '${typeof options}'`
+      );
+    }
+    validateOptions(options);
+    const { multiple = false, root = document.body, timeout = 0 } = options;
     const isMultiple = typeof multiple === "function" ? multiple() : multiple;
     if (isMultiple) {
       if (typeof target !== "string") {
@@ -978,25 +1163,50 @@ 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);
+          const instance2 = new DOMNodeReference(element, root, timeout);
           await instance2[_init]();
           return new Proxy(instance2, createProxyHandler());
         })
       );
       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) {
     throw new Error(e);
   }
 }
+function validateOptions(options) {
+  const { multiple = false, root = document.body, timeout = 0 } = options;
+  if (typeof multiple !== "boolean" && typeof multiple !== "function") {
+    throw new Error(
+      `'multiple' must be of type 'boolean' or 'function'. Received type: '${typeof multiple}'`
+    );
+  }
+  if (typeof multiple === "function") {
+    const value = multiple();
+    if (typeof value !== "boolean") {
+      throw new Error(
+        `'multiple' function must return a boolean. Received type: '${typeof value}'`
+      );
+    }
+  }
+  if (!(root instanceof HTMLElement)) {
+    throw new Error(
+      `'root' must be of type 'HTMLElement'. Received type: '${typeof root}'`
+    );
+  }
+  if (typeof timeout !== "number") {
+    throw new Error(
+      `'timeout' must be of type 'number'. Received type: '${typeof timeout}'`
+    );
+  }
+  return;
+}
 function createProxyHandler() {
   return {
     get: (target, prop) => {
@@ -1012,26 +1222,52 @@ function createProxyHandler() {
     }
   };
 }
-function enhanceArray(array) {
-  Object.defineProperties(array, {
-    hideAll: {
-      value: function() {
-        this.forEach((instance) => instance.hide());
-        return this;
-      }
-    },
-    showAll: {
-      value: function() {
-        this.forEach((instance) => instance.show());
-        return this;
+
+// src/bindForm.ts
+async function bindForm(formId) {
+  try {
+    const form = await API_default.getRecord("systemforms", formId);
+    const { formxml } = form;
+    const parser = new DOMParser();
+    const xmlDoc = parser.parseFromString(formxml, "application/xml");
+    const controls = xmlDoc.getElementsByTagName("control");
+    const dataFields = [];
+    for (let i = 0; i < controls.length; i++) {
+      const datafieldname = controls[i].getAttribute("datafieldname");
+      if (datafieldname) {
+        const refPromise = createDOMNodeReference(`#${datafieldname}`).catch((error) => {
+          console.warn(
+            `Failed to create a reference to the form field: ${datafieldname}`,
+            error
+          );
+          return null;
+        });
+        dataFields.push(refPromise);
       }
     }
-  });
-  return array;
+    const resolvedRefs = await Promise.all(dataFields);
+    return enhanceArray(
+      resolvedRefs.filter((ref) => ref !== null)
+    );
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error(error.message);
+      throw error;
+    } else {
+      console.error(error);
+      throw new Error(String(error));
+    }
+  }
 }
+
+// src/index.ts
+var toolkit = { API: API_default, createRef: createDOMNodeReference, waitFor, bindForm };
+var src_default = toolkit;
 export {
   API_default as API,
+  bindForm,
   createDOMNodeReference as createRef,
+  src_default as default,
   waitFor
 };
 

package/dist/createDOMNodeReferences.d.ts

@@ -1,9 +1,36 @@
+import { DOMNodeReferenceArray } from "./DOMNodeReferenceArray.js";
 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[]>;
+interface CreationOptions {
+    /**
+     * Should this call return an array of instantiated references, or just a single?
+     * Defaults to false, returning a single instance.
+     */
+    multiple?: (() => boolean) | boolean;
+    /**
+     * Optionally specify the element within which to search for the element targeted by 'target'.
+     * Defaults to 'document.body'.
+     */
+    root?: HTMLElement;
+    /**
+     * Optionally specify the amount of time that should be waited to find the targeted element before throwing an error.
+     * Useful for async DOM loading. Relies on MutationObserver.
+     * WARNING: Implementing multiple references with timeout can result in infinite loading.
+     */
+    timeout?: number;
+}
+export default function createDOMNodeReference(target: Element, options?: CreationOptions): Promise<DOMNodeReference>;
+export default function createDOMNodeReference(target: string, options?: Omit<CreationOptions, "multiple"> & {
+    /**
+     * Should this call return an array of instantiated references, or just a single instance?
+     * Defaults to false, returning a single instance.
+     */
+    multiple?: false;
+}): Promise<DOMNodeReference>;
+export default function createDOMNodeReference(target: string, options?: Omit<CreationOptions, "multiple"> & {
+    /**
+     * Should this call return an array of instantiated references, or just a single instance?
+     * Defaults to false, returning a single instance.
+     */
+    multiple?: true;
+}): Promise<DOMNodeReferenceArray>;
+export {};

package/dist/index.d.ts

@@ -2,4 +2,17 @@ import "./style.css";
 import API from "./API.js";
 import createRef from "./createDOMNodeReferences.js";
 import waitFor from "./waitFor.js";
-export { API, createRef, waitFor };
+import bindForm from "./bindForm.js";
+export { API, createRef, waitFor, bindForm };
+declare const toolkit: {
+    API: {
+        createRecord(tableSetName: string, data: object): Promise<string>;
+        getRecord<T>(tableSetName: string, recordID: string, selectColumns?: string): Promise<T>;
+        getMultiple(tableSetName: string, queryParameters?: string): Promise<Array<object>>;
+        updateRecord(tableSetName: string, recordId: string, data: object): Promise<any>;
+    };
+    createRef: typeof createRef;
+    waitFor: typeof waitFor;
+    bindForm: typeof bindForm;
+};
+export default toolkit;

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: Element | string, root: Element | Document, multiple: false, debounceTime: number): Promise<HTMLElement>;
+export default function waitFor(target: Element | string, root: Element | Document, multiple: true, debounceTime: number): Promise<HTMLElement[]>;

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "powerpagestoolkit",
-  "version": "2.6.02",
+  "version": "2.6.4",
   "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",
+  "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "scripts": {
     "typecheck": "tsc",
@@ -15,11 +15,13 @@
   "devDependencies": {
     "@babel/preset-env": "^7.25.8",
     "@types/node": "^22.8.6",
+    "@typescript-eslint/parser": "^8.20.0",
     "css-loader": "^7.1.2",
     "esbuild": "^0.24.0",
     "esbuild-css-modules-plugin": "^3.1.2",
     "eslint": "^8.57.1",
     "eslint-plugin-import": "^2.31.0",
+    "globals": "^15.14.0",
     "rimraf": "^6.0.1",
     "ts-loader": "^9.5.1",
     "typescript": "^5.6.3",