powerpagestoolkit 2.6.3327 → 2.7.0

package/README.md

@@ -95,7 +95,8 @@ 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
+
+// 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 });
 

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,33 @@
+interface IBusinessRule {
+    /**
+     * @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 clearValuesOnHide Should the values in the targeted field be cleared when hidden? Defaults to true
+     */
+    setVisibility?: [condition: () => boolean, clearValuesOnHide?: boolean];
+    /**
+     * @param isRequired Function determining if field is required
+     * @param isValid Function validating field input. allows access to the invoked expression passed by {@link isRequired}
+     */
+    setRequired?: [
+        isRequired: () => boolean,
+        isValid: (isRequired: () => boolean) => boolean
+    ];
+    /**
+     * @param condition A function to determine if the value provided should be applied to this field
+     * @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
+     */
+    setDisabled?: [condition: () => boolean];
+}
 export declare const _init: unique symbol;
 declare const _destroy: unique symbol;
 declare const _valueSync: unique symbol;
@@ -11,8 +41,9 @@ declare const _debounceTime: unique symbol;
 declare const _observers: unique symbol;
 declare const _boundEventListeners: unique symbol;
 export default class DOMNodeReference {
-    target: HTMLElement | string;
-    root: HTMLElement;
+    target: Element | string;
+    logicalName?: string;
+    root: Element;
     private [_debounceTime];
     private isLoaded;
     private defaultDisplay;
@@ -49,8 +80,9 @@ export default class DOMNodeReference {
      * @param root - Optionally specify the element within to search for the element targeted by 'target'
      * Defaults to 'document.body'
      */
-    /******/ /******/ constructor(target: HTMLElement | string, root: HTMLElement | undefined, debounceTime: number);
+    /******/ /******/ constructor(target: Element | string, root: Element | undefined, debounceTime: number);
     [_init](): Promise<void>;
+    private eventMapping;
     /**
      * Initializes value synchronization with appropriate event listeners
      * based on element type.
@@ -187,7 +219,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;
@@ -196,52 +228,61 @@ 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.
+     * @param dependencies For re-evaluation conditions when the state of the dependencies change
+     * @returns Instance of this for method chaining.
+     */
+    applyBusinessRule(rule: IBusinessRule, dependencies: DOMNodeReference[]): 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. clearValuesOnHide defaults to false.
+     * all other options defaults to true
      */
     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,6 +102,40 @@ 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.target.toString().replace(/[#\[\]]/g, "") === prop || instance.logicalName === prop
+        );
+      }
+      return void 0;
+    }
+  });
+}
+
 // src/waitFor.ts
 function waitFor(target, root = document, multiple = false, debounceTime) {
   return new Promise((resolve, reject) => {
@@ -130,7 +164,7 @@ function waitFor(target, root = document, multiple = false, debounceTime) {
           } else {
             reject(
               new Error(
-                `No elements found with target: "${target}" within ${debounceTime / 1e3} seconds. If the element you are expected has not loaded yet, consider raising your timeout.`
+                `No elements found with target: "${target}" within ${debounceTime / 1e3} seconds. If the element you are expecting has not loaded yet, consider raising your timeout.`
               )
             );
           }
@@ -154,7 +188,7 @@ function waitFor(target, root = document, multiple = false, debounceTime) {
         observer.disconnect();
         reject(
           new Error(
-            `Element not found by target: "${target}" within ${debounceTime / 1e3} second. If the element you are expected has not loaded yet, consider raising your timeout.`
+            `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);
@@ -285,6 +319,7 @@ var _boundEventListeners = Symbol("BEV");
 var DOMNodeReference = class _DOMNodeReference {
   // properties initialized in the constructor
   target;
+  logicalName;
   root;
   [_debounceTime];
   isLoaded;
@@ -306,6 +341,18 @@ var DOMNodeReference = class _DOMNodeReference {
   /******/
   constructor(target, root = document.body, debounceTime) {
     this.target = target;
+    if (typeof target === "string") {
+      let lName = null;
+      const bracketMatch = target.match(/\[([^\]]+)\]/);
+      if (bracketMatch) {
+        lName = bracketMatch[1];
+        const quoteMatch = lName.match(/["']([^"']+)["']/);
+        if (quoteMatch) {
+          lName = quoteMatch[1];
+        }
+      }
+      this.logicalName = (lName || target).replace(/[#\[\]]/g, "");
+    }
     this.root = root;
     this[_debounceTime] = debounceTime;
     this.isLoaded = false;
@@ -348,6 +395,14 @@ var DOMNodeReference = class _DOMNodeReference {
       throw new DOMNodeInitializationError(this, errorMessage);
     }
   }
+  eventMapping = {
+    checkbox: "click",
+    radio: "click",
+    select: "change",
+    "select-multiple": "change",
+    textarea: "keyup"
+    // Add other input types as needed
+  };
   /**
    * Initializes value synchronization with appropriate event listeners
    * based on element type.
@@ -356,30 +411,20 @@ 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"
-        // 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 = this.eventMapping[this.element.type] ?? "input";
+      } else if (this.element instanceof HTMLTextAreaElement) {
+        eventType = this.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,
+        element: this.element,
+        handler: this.updateValue,
         event: eventType
       });
       if (this.element instanceof HTMLInputElement && this.element.dataset.type === "date") {
@@ -436,8 +481,11 @@ var DOMNodeReference = class _DOMNodeReference {
           value: input.value !== "" ? Number(input.value) : null
         };
       default:
+        let cleanValue = input.value;
+        if (this.element.classList.contains("decimal") || this.element.classList.contains("money"))
+          cleanValue = input.value.replace(/[$,]/g, "");
         return {
-          value: this.element.classList.contains("decimal") || this.element.classList.contains("money") ? parseFloat(input.value) : input.value
+          value: this.element.classList.contains("decimal") || this.element.classList.contains("money") ? parseFloat(cleanValue) : cleanValue
         };
     }
   }
@@ -481,7 +529,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);
@@ -579,9 +628,21 @@ var DOMNodeReference = class _DOMNodeReference {
     if (value instanceof Function) {
       value = value();
     }
-    if (this.element.classList.contains("boolean-radio")) {
+    let eventType;
+    if (this.element instanceof HTMLSelectElement) {
+      eventType = "change";
+    } else if (this.element instanceof HTMLInputElement) {
+      eventType = this.eventMapping[this.element.type] ?? "input";
+    } else if (this.element instanceof HTMLTextAreaElement) {
+      eventType = this.eventMapping[this.element.type] ?? "input";
+    } else {
+      eventType = "input";
+    }
+    this.element.dispatchEvent(new Event(eventType, { bubbles: false }));
+    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;
+      this.value = value;
     } else {
       this.element.value = value;
     }
@@ -770,7 +831,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) {
@@ -779,7 +840,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;
@@ -799,18 +861,127 @@ 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.
+   * @param dependencies For re-evaluation conditions when the state of the dependencies change
+   * @returns Instance of this for method chaining.
+   */
+  applyBusinessRule(rule, dependencies) {
+    try {
+      if (rule.setVisibility) {
+        const [condition, clearValuesOnHide = true] = rule.setVisibility;
+        const initialState = condition.bind(this)();
+        this.toggleVisibility(initialState);
+        if (dependencies.length) {
+          this._configDependencyTracking(
+            () => this.toggleVisibility(condition.bind(this)()),
+            dependencies,
+            {
+              clearValuesOnHide,
+              observeVisibility: true,
+              trackInputEvents: false,
+              trackRadioButtons: false
+            }
+          );
+        }
+      }
+      if (rule.setRequired) {
+        const [isRequired, isValid] = rule.setRequired;
+        const fieldDisplayName = (() => {
+          let label = this.getLabel();
+          if (!label)
+            return new Error(
+              `There was an error accessing the label for this element: ${String(
+                this.target
+              )}`
+            );
+          label = label.innerHTML;
+          if (label.length > 50) {
+            label = label.substring(0, 50) + "...";
+          }
+          return label;
+        })();
+        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.bind(this)();
+            const isFieldVisible = window.getComputedStyle(this.visibilityController).display !== "none";
+            return !isFieldRequired || !isFieldVisible || isValid.bind(this)(isRequired.bind(this));
+          }
+        });
+        Page_Validators.push(newValidator);
+        this.setRequiredLevel(isRequired.bind(this)());
+        this._configDependencyTracking(
+          () => this.setRequiredLevel(isRequired.bind(this)()),
+          dependencies,
+          { clearValuesOnHide: false }
+        );
+      }
+      if (rule.setValue) {
+        const [condition, value] = rule.setValue;
+        if (condition.bind(this)()) {
+          this.setValue.bind(this)(value);
+        }
+        if (dependencies.length) {
+          this._configDependencyTracking(
+            () => {
+              if (condition.bind(this)()) {
+                this.setValue.bind(this)(value);
+              }
+            },
+            dependencies,
+            { clearValuesOnHide: false }
+          );
+        }
+      }
+      if (rule.setDisabled) {
+        const [condition] = rule.setDisabled;
+        condition.bind(this)() ? this.disable() : this.enable();
+        if (dependencies.length) {
+          this._configDependencyTracking(
+            () => {
+              condition.bind(this)() ? this.enable() : this.disable();
+            },
+            dependencies,
+            {
+              clearValuesOnHide: false,
+              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 {
@@ -844,13 +1015,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()) {
@@ -899,9 +1070,10 @@ 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. clearValuesOnHide defaults to false.
+   * all other options defaults to true
    */
   _configDependencyTracking(handler, dependencies, options = {
     clearValuesOnHide: false,
@@ -978,9 +1150,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) {
@@ -995,7 +1167,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) {
@@ -1034,22 +1206,8 @@ async function createDOMNodeReference(target, options = {
         `'options' must be of type 'object'. Received type: '${typeof options}'`
       );
     }
+    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 (!(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}'`
-      );
-    }
     const isMultiple = typeof multiple === "function" ? multiple() : multiple;
     if (isMultiple) {
       if (typeof target !== "string") {
@@ -1074,6 +1232,33 @@ async function createDOMNodeReference(target, options = {
     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) => {
@@ -1089,25 +1274,62 @@ 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 = processElements(xmlDoc.getElementsByTagName("control"));
+    const sections = processElements(xmlDoc.getElementsByTagName("section"));
+    const tabs = processElements(xmlDoc.getElementsByTagName("tab"));
+    const resolvedRefs = await Promise.all([...controls, ...sections, ...tabs]);
+    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));
     }
-  });
-  return array;
+  }
+}
+function processElements(element) {
+  return Array.from(element).map((element2) => {
+    const identifyingAttribute = getIdentifyingAttribute(element2.tagName);
+    const datafieldname = element2.getAttribute(identifyingAttribute);
+    if (!datafieldname) return null;
+    const referenceString = createReferenceString(
+      element2.tagName,
+      datafieldname
+    );
+    if (!referenceString) return null;
+    return createDOMNodeReference(referenceString).catch((error) => {
+      console.warn(
+        `Failed to create a reference to the form field: ${datafieldname}`,
+        error
+      );
+      return null;
+    });
+  }).filter(Boolean);
+}
+function getIdentifyingAttribute(tagName) {
+  return tagName === "control" ? "id" : tagName === "tab" || tagName === "section" ? "name" : "id";
+}
+function createReferenceString(tagName, datafieldname) {
+  if (tagName === "control") return `#${datafieldname}`;
+  if (tagName === "tab" || tagName === "section")
+    return `[data-name="${datafieldname}"]`;
+  return null;
 }
 export {
   API_default as API,
+  bindForm,
   createDOMNodeReference as createRef,
   waitFor
 };

package/dist/createDOMNodeReferences.d.ts

@@ -1,11 +1,36 @@
+import { DOMNodeReferenceArray } from "./DOMNodeReferenceArray.js";
 import DOMNodeReference from "./DOMNodeReference.js";
-export default function createDOMNodeReference(target: HTMLElement | string, options?: {
-    multiple?: (() => boolean) | false;
+interface ICreationOptions {
+    /**
+     * 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?: ICreationOptions): Promise<DOMNodeReference>;
+export default function createDOMNodeReference(target: string, options?: Omit<ICreationOptions, "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?: {
-    multiple?: (() => true) | true;
-    root?: HTMLElement;
-    timeout?: number;
-}): Promise<DOMNodeReference[]>;
+export default function createDOMNodeReference(target: string, options?: Omit<ICreationOptions, "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,5 @@ 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 };

package/dist/waitFor.d.ts

@@ -1,2 +1,2 @@
-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[]>;
+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.3327",
+  "version": "2.7.0",
   "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",