powerpagestoolkit 2.6.33311 → 2.7.1

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 });
 
@@ -141,76 +142,113 @@ node.on("click", function (e) {
 ...
 ```
 
-##### Visibility Control
+##### Business Rule Application
 
-```typescript
-// Basic visibility
-node.hide();
-node.show();
-```
+This utility provides a flexible way to dynamically control field visibility, requirement status, values, and enabled states based on dependencies within PowerPages forms.
 
-**_Advanced conditional rendering_**
+_Method Signature:_
 
-Out of the box, Microsoft does not provide PowerPages developers the ability to hide or show fields or form elements based on the value of another field. This method allows such configurations
+```typescript
+applyBusinessRule(
+  rule: IBusinessRule,
+  dependencies: DOMNodeReference[]
+): DOMNodeReference; /* Instance of this is returned for optional
+ method chaining */
+```
 
-_Method signature:_
+**BusinessRule Definition**
 
 ```typescript
-configureConditionalRendering(
-    condition: () => boolean,
-    dependencies?: DOMNodeReference[],
-    clearValuesOnHide: boolean = true
-  ): DOMNodeReference /* Instance of this returned
-  for optional method chaining */
+interface IBusinessRule {
+  setVisibility?: [
+    condition: () => boolean, 
+    clearValuesOnHide?: boolean = true
+    ];
+  setRequired?: [
+    isRequired: () => boolean,
+    isValid: () => boolean
+  ];
+  setValue?: [
+    condition: () => boolean, 
+    value: () => any | any
+    ];
+  setDisabled?: () => boolean;
+}
 ```
 
-_Example implementation:_
+##### Visibility Control
 
 ```typescript
-node.configureConditionalRendering(
-  function () // Function to evaluate wether this node should be visible or not
+// Show the 'taxIdField' only when
+// 'businessTypeField' is set to 'Corporation' or 'LLC'
+taxIdField.applyBusinessRule(
   {
-    return otherNode.value === "some value";
+    setVisibility: [
+      () =>
+        businessTypeField.value === "Corporation" ||
+        businessTypeField.value === "LLC",
+    ],
   },
-  [otherNode] /* Dependency array | if the values or visibility of these
-  change, the function is re-evaluated */,
+  [businessTypeField] // Re-evaluate when businessTypeField changes
+);
 
-  true /* should the values in the targeted elements (this.element)
-  be cleared if this node is hidden? Default = true */
+// Optionally disable 'clearValuesOnHide:
+taxIdField.applyBusinessRule(
+  {
+    setVisibility: [
+      () =>
+        businessTypeField.value === "Corporation" ||
+        businessTypeField.value === "LLC",
+      false, // defaults to true. False will prevent the fields from losing it's value if it is hidden
+    ],
+  },
+  [businessTypeField] // Re-evaluate when businessTypeField changes
 );
 ```
 
 ##### Validation and Requirements
 
-This utility enhances PowerPages forms by adding dynamic field validation and conditional requirements based on other field values.
-
-_Method signature:_
-
 ```typescript
-configureValidationAndRequirements(
-  isRequired: () => boolean,
-  isValid: () => boolean,
-  fieldDisplayName: string,
-  dependencies: DOMNodeReference[]
-): DOMNodeReference; /* instance of this is returned for optional
- method chaining */
+// Require 'taxIdField' when 'businessTypeField' is 'Corporation' or 'LLC'
+taxIdField.applyBusinessRule(
+  {
+    setRequired: [
+      function () {
+        return (
+          businessTypeField.value === "Corporation" ||
+          businessTypeField.value === "LLC"
+        );
+      },
+      function () {
+        return this.value != null && this.value !== "";
+      },
+    ],
+  },
+  [businessTypeField] // Revalidate when businessTypeField changes
+);
 ```
 
-_Example implementation:_
+##### Setting Field Values Conditionally
 
 ```typescript
-node.configureValidationAndRequirements(
-  // Make field required only when "Yes" is checked
-  () => dependentNode.yesRadio?.checked ?? false,
-
-  // Basic validation: ensure field isn't empty
-  function () {
-    return this.value != null && this.value !== "";
+// Set default industry value when 'businessTypeField' is 'Corporation'
+industryField.applyBusinessRule(
+  {
+    setValue: [() => businessTypeField.value === "Corporation", "Corporate"],
   },
+  [businessTypeField] // Apply value when businessTypeField changes
+);
+```
 
-  "Contact Phone", // Shows in error message: "Contact Phone is required"
+##### Enabling and Disabling Fields
 
-  [dependentNode] // Revalidate when dependentNode changes
+```typescript
+// Disable 'taxIdField' when 'businessTypeField' is 'Individual'
+taxIdField.applyBusinessRule(
+  {
+    setDisabled: [() => businessTypeField.value === "Individual"],
+  },
+  [businessTypeField] // Enable/disable when businessTypeField changes
 );
 ```
 
@@ -260,7 +298,6 @@ _Enabling/Disabling inputs_
 ```typescript
 node.disable();
 node.enable();
-
 ```
 
 ##### Label and Tooltip Management
@@ -294,6 +331,89 @@ title.addTooltip("This is an Example of a tooltip!", { color: "red" });
 
 ![Example](./assets//infoIconExample.gif)
 
+Here's an improved markdown documentation with more comprehensive details:
+
+### BindForm Method
+
+The `bindForm` method simplifies form element management in DataVerse by providing a semantic and efficient way to access form controls, sections, and tabs.
+
+##### Key Features
+
+- Retrieves form definition directly from DataVerse
+- Automatically generates references for:
+  - Controls
+  - Sections
+  - Tabs
+
+##### Element Types
+
+| Element Type | Description                                 | Accessibility             |
+| ------------ | ------------------------------------------- | ------------------------- |
+| `control`    | Includes all form fields and sub-grids      | Accessed via logical name |
+| `section`    | Standard PowerApps form sections            | Accessed via logical name |
+| `tab`        | Form tabs corresponding to PowerApps layout | Accessed via logical name |
+
+##### Usage Example
+
+```javascript
+import { bindForm } from "powerpagestoolkit";
+
+// Basic form binding
+bindForm("form-guid").then((form) => {
+  // Access elements by their logical name
+  const nameField = form["name"];
+
+  // execute custom methods
+  nameField.applyBusinessRule(
+    {
+      setVisibility: [() => someNode.value === "desired value"],
+    },
+    [someNode]
+  );
+
+  // Or executes methods immediately upon accessing
+  form["phonenumber"].addTooltip("Example tooltip text");
+});
+```
+
+##### Method Signature
+
+```typescript
+/**
+ * Binds a form by its GUID and returns a collection of form elements
+ * @param formGuid Unique identifier for the form
+ * @returns Promise resolving to form element references
+ */
+function bindForm(formGuid: string): Promise<DOMNodeReferenceArray & Record<string: DOMNodeReference>>;
+```
+
+##### Benefits
+
+- Reduces code complexity
+- Improves readability
+- Provides type-safe access to form elements
+- Supports flexible form interactions
+
+##### Best Practices
+
+- Use logical names consistently
+- Handle async nature of form binding
+- Leverage TypeScript for enhanced type checking
+
+##### Error Handling
+
+Ensure proper error handling for form binding:
+
+```javascript
+bindForm("form-guid")
+  .then((form) => {
+    // Form processing
+  })
+  .catch((error) => {
+    console.error("Form binding failed", error);
+  });
+```
+
 ### DataVerse API
 
 Perform secure API calls to DataVerse from your PowerPages site. This method implements the shell deferred token to send requests with `__RequestVerificationToken`

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,30 @@
+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.
+     */
+    setRequired?: [isRequired: () => boolean, isValid: () => 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 | 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?: () => boolean;
+}
 export declare const _init: unique symbol;
 declare const _destroy: unique symbol;
 declare const _valueSync: unique symbol;
@@ -11,8 +38,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 +77,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.
@@ -196,52 +225,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
         };
     }
   }
@@ -580,9 +628,21 @@ var DOMNodeReference = class _DOMNodeReference {
     if (value instanceof Function) {
       value = value();
     }
+    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;
     }
@@ -801,18 +861,128 @@ 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)();
+          }
+        });
+        Page_Validators.push(newValidator);
+        this.setRequiredLevel(isRequired.bind(this)());
+        this._configDependencyTracking(
+          () => this.setRequiredLevel(isRequired.bind(this)()),
+          dependencies,
+          { clearValuesOnHide: false }
+        );
+      }
+      if (rule.setValue) {
+        let [condition, value] = rule.setValue;
+        if (value instanceof Function) value = value();
+        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 {
@@ -846,13 +1016,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()) {
@@ -901,9 +1071,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,
@@ -980,9 +1151,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) {
@@ -997,7 +1168,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) {
@@ -1104,25 +1275,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.33311",
+  "version": "2.7.001",
   "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",