powerpagestoolkit 2.7.0 → 2.7.101

package/README.md

@@ -85,10 +85,10 @@ import { createRef } from "powerpagestoolkit";
 Instantiate one, or multiple instances of a DOMNodeReference, and optionally configure advanced options
 
 ```javascript
-// Create a single reference
+// Create a single reference (i.e. 'querySelector')
 const node = await createRef("#myElement");
 
-// Create multiple references
+// Create multiple references (i.e. 'querySelectorAll')
 const nodes = await createRef(".my-class", { multiple: true });
 
 /******************/
@@ -142,76 +142,116 @@ 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(
+interface IBusinessRule {
+  setVisibility?: [
     condition: () => boolean,
-    dependencies?: DOMNodeReference[],
-    clearValuesOnHide: boolean = true
-  ): DOMNodeReference /* Instance of this returned
-  for optional method chaining */
+    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
 );
 ```
 
@@ -261,7 +301,6 @@ _Enabling/Disabling inputs_
 ```typescript
 node.disable();
 node.enable();
-
 ```
 
 ##### Label and Tooltip Management
@@ -295,6 +334,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/bundle.js

@@ -1,4 +1,4 @@
-// src/safeAjax.ts
+// src/utils/safeAjax.ts
 function safeAjax(ajaxOptions) {
   const deferredAjax = $.Deferred();
   shell.getTokenDeferred().done(function(token) {
@@ -20,7 +20,7 @@ function safeAjax(ajaxOptions) {
   return deferredAjax.promise();
 }
 
-// src/API.ts
+// src/core/API.ts
 var API = {
   /**
    * @param tableSetName The dataverse set name for the table that you are updating a record in
@@ -102,48 +102,14 @@ 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) {
+// src/utils/waitFor.ts
+function waitFor(target, root = document, multiple = false, debounceTime2) {
   return new Promise((resolve, reject) => {
     if (multiple) {
       let timeout;
       const observedElements = [];
       const observedSet = /* @__PURE__ */ new Set();
-      if (debounceTime < 1) {
+      if (debounceTime2 < 1) {
         return resolve(
           Array.from(root.querySelectorAll(target))
         );
@@ -164,11 +130,11 @@ 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 expecting has not loaded yet, consider raising your timeout.`
+                `No elements found with target: "${target}" within ${debounceTime2 / 1e3} seconds. If the element you are expecting has not loaded yet, consider raising your timeout.`
               )
             );
           }
-        }, debounceTime);
+        }, debounceTime2);
       });
       observer.observe(root, {
         childList: true,
@@ -188,10 +154,10 @@ 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 expecting has not loaded yet, consider raising your timeout.`
+            `Element not found by target: "${target}" within ${debounceTime2 / 1e3} second. If the element you are expecting has not loaded yet, consider raising your timeout.`
           )
         );
-      }, debounceTime);
+      }, debounceTime2);
       if (target instanceof HTMLElement) {
         clearTimeout(timeout);
         return resolve(target);
@@ -211,7 +177,7 @@ function waitFor(target, root = document, multiple = false, debounceTime) {
   });
 }
 
-// src/createInfoElement.ts
+// src/utils/createInfoElement.ts
 function CreateInfoEl(titleString, iconStyle) {
   if (typeof titleString !== "string") {
     throw new Error(
@@ -275,7 +241,22 @@ function CreateInfoEl(titleString, iconStyle) {
   return span;
 }
 
-// src/errors.ts
+// src/constants/symbols.ts
+var init = Symbol("__I");
+var destroy = Symbol("__D");
+var valueSync = Symbol("__VS");
+var dateSync = Symbol("__DS");
+var getElementValue = Symbol("__GEV");
+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 isValidFormElement = Symbol("__VFE");
+var registerEventListener = Symbol("__REV");
+
+// src/errors/errors.ts
 var DOMNodeInitializationError = class extends Error {
   constructor(instance, error) {
     super(
@@ -303,29 +284,27 @@ var ValidationConfigError = class extends Error {
   }
 };
 
-// src/DOMNodeReference.ts
-var _init = Symbol("_I");
-var _destroy = Symbol("_D");
-var _valueSync = Symbol("_VS");
-var _dateSync = Symbol("_DS");
-var _getElementValue = Symbol("_GEV");
-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");
+// src/core/DOMNodeReference.ts
+var eventMapping = {
+  checkbox: "click",
+  radio: "click",
+  select: "change",
+  "select-multiple": "change",
+  textarea: "keyup"
+  // Add other input types as needed
+};
 var DOMNodeReference = class _DOMNodeReference {
   // properties initialized in the constructor
   target;
   logicalName;
   root;
-  [_debounceTime];
+  [debounceTime];
   isLoaded;
   defaultDisplay;
-  [_observers] = [];
-  [_boundEventListeners] = [];
+  [observers] = [];
+  [boundEventListeners] = [];
+  isRadio = false;
+  radioType = null;
   /**
    * The value of the element that this node represents
    * stays in syncs with the live DOM elements?.,m  via event handler
@@ -339,7 +318,7 @@ var DOMNodeReference = class _DOMNodeReference {
    */
   /******/
   /******/
-  constructor(target, root = document.body, debounceTime) {
+  constructor(target, root = document.body, debounceTime2) {
     this.target = target;
     if (typeof target === "string") {
       let lName = null;
@@ -354,32 +333,39 @@ var DOMNodeReference = class _DOMNodeReference {
       this.logicalName = (lName || target).replace(/[#\[\]]/g, "");
     }
     this.root = root;
-    this[_debounceTime] = debounceTime;
+    this[debounceTime] = debounceTime2;
     this.isLoaded = false;
     this.defaultDisplay = "";
     this.value = null;
-    this[_bindMethods]();
+    this[bindMethods]();
   }
-  async [_init]() {
+  async [init]() {
     try {
       if (this.target instanceof HTMLElement) {
         this.element = this.target;
       } else {
-        this.element = await waitFor(this.target, this.root, false, this[_debounceTime]);
+        this.element = await waitFor(
+          this.target,
+          this.root,
+          false,
+          this[debounceTime]
+        );
       }
       if (!this.element) {
         throw new DOMNodeNotFoundError(this);
       }
-      if (this.element.classList.contains("boolean-radio")) {
-        await this[_attachRadioButtons]();
+      if (this.element.id && this.element.querySelectorAll(
+        `#${this.element.id} > input[type="radio"]`
+      ).length > 0) {
+        await this[attachRadioButtons]();
       }
-      this[_valueSync]();
-      this[_attachVisibilityController]();
+      this[valueSync]();
+      this[attachVisibilityController]();
       this.defaultDisplay = this.visibilityController.style.display;
       const observer = new MutationObserver((mutations) => {
         for (const mutation of mutations) {
           if (Array.from(mutation.removedNodes).includes(this.element)) {
-            this[_destroy]();
+            this[destroy]();
             observer.disconnect();
             break;
           }
@@ -395,40 +381,27 @@ 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.
-   * @private
    */
-  async [_valueSync]() {
+  async [valueSync]() {
     try {
+      if (!this[isValidFormElement](this.element)) return;
       this.updateValue();
       let eventType;
       if (this.element instanceof HTMLSelectElement) {
         eventType = "change";
       } else if (this.element instanceof HTMLInputElement) {
-        eventType = this.eventMapping[this.element.type] ?? "input";
+        eventType = eventMapping[this.element.type] ?? "input";
       } else if (this.element instanceof HTMLTextAreaElement) {
-        eventType = this.eventMapping[this.element.type] ?? "input";
+        eventType = eventMapping[this.element.type] ?? "input";
       } else {
         eventType = "input";
       }
-      this.element.addEventListener(eventType, this.updateValue);
-      this[_boundEventListeners].push({
-        element: this.element,
-        handler: this.updateValue,
-        event: eventType
-      });
+      this[registerEventListener](this.element, eventType, this.updateValue);
       if (this.element instanceof HTMLInputElement && this.element.dataset.type === "date") {
-        await this[_dateSync](this.element);
+        await this[dateSync](this.element);
       }
     } catch (error) {
       throw new DOMNodeInitializationError(
@@ -437,28 +410,44 @@ var DOMNodeReference = class _DOMNodeReference {
       );
     }
   }
-  async [_dateSync](element) {
+  [isValidFormElement](element) {
+    return element instanceof HTMLInputElement || element instanceof HTMLSelectElement || element instanceof HTMLTextAreaElement || element instanceof HTMLSpanElement || element instanceof HTMLButtonElement || element instanceof HTMLFieldSetElement;
+  }
+  [registerEventListener](element, eventType, handler) {
+    element.addEventListener(eventType, handler);
+    this[boundEventListeners].push({
+      element,
+      handler,
+      event: eventType
+    });
+  }
+  async [dateSync](element) {
     const parentElement = element.parentElement;
     if (!parentElement) {
       throw new Error("Date input must have a parent element");
     }
-    const dateNode = await waitFor("[data-date-format]", parentElement, false, 1500);
-    dateNode.addEventListener("select", this.updateValue);
-    const _handler = this.updateValue;
-    this[_boundEventListeners].push({
-      element: dateNode,
-      handler: _handler,
-      event: "select"
-    });
+    const dateNode = await waitFor(
+      "[data-date-format]",
+      parentElement,
+      false,
+      1500
+    );
+    this[registerEventListener](dateNode, "select", this.updateValue);
   }
   /**
    * Gets the current value of the element based on its type
-   * @private
+   * @protected
    * @returns Object containing value and optional checked state
    */
-  [_getElementValue]() {
+  [getElementValue]() {
     const input = this.element;
     const select = this.element;
+    if (this.yesRadio instanceof _DOMNodeReference && this.noRadio instanceof _DOMNodeReference) {
+      return {
+        value: this.yesRadio.checked,
+        checked: this.yesRadio.checked
+      };
+    }
     switch (input.type) {
       case "checkbox":
       case "radio":
@@ -489,19 +478,7 @@ var DOMNodeReference = class _DOMNodeReference {
         };
     }
   }
-  /**
-   * Updates related radio buttons if this is part of a radio group
-   * @private
-   */
-  [_updateRadioGroup]() {
-    if (this.yesRadio instanceof _DOMNodeReference && this.noRadio instanceof _DOMNodeReference) {
-      this.yesRadio.updateValue();
-      this.noRadio?.updateValue();
-      this.checked = this.yesRadio.checked;
-      this.value = this.yesRadio.checked;
-    }
-  }
-  [_attachVisibilityController]() {
+  [attachVisibilityController]() {
     this.visibilityController = this.element;
     if (this.element.tagName === "TABLE") {
       const fieldset = this.element.closest("fieldset");
@@ -524,11 +501,26 @@ var DOMNodeReference = class _DOMNodeReference {
       }
     }
   }
-  async [_attachRadioButtons]() {
-    this.yesRadio = await createDOMNodeReference(`#${this.element.id}_1`);
-    this.noRadio = await createDOMNodeReference(`#${this.element.id}_0`);
+  async [attachRadioButtons]() {
+    if (!this.element) {
+      console.error(
+        "'this.element' not found: cannot attach radio buttons for ",
+        this.target
+      );
+      return;
+    }
+    this.yesRadio = await createDOMNodeReference('input[type="radio"][value="1"]', {
+      root: this.element
+    });
+    this.yesRadio.isRadio = true;
+    this.yesRadio.radioType = "truthy";
+    this.noRadio = await createDOMNodeReference('input[type="radio"][value="0"]', {
+      root: this.element
+    });
+    this.noRadio.isRadio = true;
+    this.noRadio.radioType = "falsy";
   }
-  [_bindMethods]() {
+  [bindMethods]() {
     const prototype = Object.getPrototypeOf(this);
     for (const key of Object.getOwnPropertyNames(prototype)) {
       const value = this[key];
@@ -537,15 +529,15 @@ var DOMNodeReference = class _DOMNodeReference {
       }
     }
   }
-  [_destroy]() {
-    this[_boundEventListeners]?.forEach((binding) => {
+  [destroy]() {
+    this[boundEventListeners]?.forEach((binding) => {
       binding.element?.removeEventListener(binding.event, binding.handler);
     });
-    this[_observers]?.forEach((observer) => {
+    this[observers]?.forEach((observer) => {
       observer.disconnect();
     });
-    this.yesRadio?.[_destroy]();
-    this.noRadio?.[_destroy]();
+    this.yesRadio?.[destroy]();
+    this.noRadio?.[destroy]();
     this.yesRadio = null;
     this.noRadio = null;
     this.isLoaded = false;
@@ -555,13 +547,19 @@ var DOMNodeReference = class _DOMNodeReference {
    * Updates the value and checked state based on element type
    * @public
    */
-  updateValue() {
-    const elementValue = this[_getElementValue]();
+  updateValue(e) {
+    if (e) {
+      e.stopPropagation();
+    }
+    if (this.yesRadio && this.noRadio) {
+      this.yesRadio.updateValue();
+      this.noRadio.updateValue();
+    }
+    const elementValue = this[getElementValue]();
     this.value = elementValue.value;
     if (elementValue.checked !== void 0) {
       this.checked = elementValue.checked;
     }
-    this[_updateRadioGroup]();
   }
   /**
    * Sets up an event listener based on the specified event type, executing the specified
@@ -577,14 +575,11 @@ var DOMNodeReference = class _DOMNodeReference {
         `Argument "eventHandler" must be a Function. Received: ${typeof eventHandler}`
       );
     }
-    this.element.addEventListener(eventType, eventHandler.bind(this));
-    const _element = this.element;
-    const _handler = eventHandler;
-    this[_boundEventListeners].push({
-      element: _element,
-      handler: _handler,
-      event: eventType
-    });
+    this[registerEventListener](
+      this.element,
+      eventType,
+      eventHandler.bind(this)
+    );
     return this;
   }
   /**
@@ -632,9 +627,9 @@ var DOMNodeReference = class _DOMNodeReference {
     if (this.element instanceof HTMLSelectElement) {
       eventType = "change";
     } else if (this.element instanceof HTMLInputElement) {
-      eventType = this.eventMapping[this.element.type] ?? "input";
+      eventType = eventMapping[this.element.type] ?? "input";
     } else if (this.element instanceof HTMLTextAreaElement) {
-      eventType = this.eventMapping[this.element.type] ?? "input";
+      eventType = eventMapping[this.element.type] ?? "input";
     } else {
       eventType = "input";
     }
@@ -711,7 +706,9 @@ var DOMNodeReference = class _DOMNodeReference {
         );
         if (childInputs.length > 0) {
           const promises = childInputs.map(async (input) => {
-            const inputRef = await createDOMNodeReference(input, { multiple: false });
+            const inputRef = await createDOMNodeReference(input, {
+              multiple: false
+            });
             return inputRef.clearValue();
           });
           await Promise.all(promises);
@@ -851,7 +848,7 @@ var DOMNodeReference = class _DOMNodeReference {
    * @returns - Instance of this [provides option to method chain]
    */
   uncheckRadios() {
-    if (this.yesRadio && this.noRadio) {
+    if (this.yesRadio instanceof _DOMNodeReference && this.noRadio instanceof _DOMNodeReference) {
       this.yesRadio.element.checked = false;
       this.noRadio.element.checked = false;
     } else {
@@ -916,7 +913,7 @@ var DOMNodeReference = class _DOMNodeReference {
           evaluationfunction: () => {
             const isFieldRequired = isRequired.bind(this)();
             const isFieldVisible = window.getComputedStyle(this.visibilityController).display !== "none";
-            return !isFieldRequired || !isFieldVisible || isValid.bind(this)(isRequired.bind(this));
+            return !isFieldRequired || !isFieldVisible || isValid.bind(this)();
           }
         });
         Page_Validators.push(newValidator);
@@ -928,7 +925,8 @@ var DOMNodeReference = class _DOMNodeReference {
         );
       }
       if (rule.setValue) {
-        const [condition, value] = rule.setValue;
+        let [condition, value] = rule.setValue;
+        if (value instanceof Function) value = value();
         if (condition.bind(this)()) {
           this.setValue.bind(this)(value);
         }
@@ -945,7 +943,7 @@ var DOMNodeReference = class _DOMNodeReference {
         }
       }
       if (rule.setDisabled) {
-        const [condition] = rule.setDisabled;
+        const condition = rule.setDisabled;
         condition.bind(this)() ? this.disable() : this.enable();
         if (dependencies.length) {
           this._configDependencyTracking(
@@ -1069,7 +1067,7 @@ var DOMNodeReference = class _DOMNodeReference {
   }
   /**
    * Sets up tracking for dependencies using both event listeners and mutation observers.
-   * @private
+   * @protected
    * @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.
@@ -1105,19 +1103,9 @@ var DOMNodeReference = class _DOMNodeReference {
           this.clearValue();
         }
       };
-      dep.on("change", handleChange);
-      this[_boundEventListeners].push({
-        element: dep.element,
-        event: "change",
-        handler: handleChange
-      });
+      this[registerEventListener](dep.element, "change", handleChange);
       if (trackInputEvents) {
-        dep.on("input", handleChange);
-        this[_boundEventListeners].push({
-          element: dep.element,
-          event: "input",
-          handler: handleChange
-        });
+        this[registerEventListener](dep.element, "input", handleChange);
       }
       if (observeVisibility) {
         const observer = new MutationObserver(() => {
@@ -1133,12 +1121,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
@@ -1190,11 +1178,47 @@ var DOMNodeReference = class _DOMNodeReference {
       subtree: true,
       childList: true
     });
-    this[_observers].push(observer);
+    this[observers].push(observer);
+  }
+};
+
+// src/core/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;
   }
 };
 
-// src/createDOMNodeReferences.ts
+// src/utils/enhanceArray.ts
+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/core/createDOMNodeReferences.ts
 async function createDOMNodeReference(target, options = {
   multiple: false,
   root: document.body,
@@ -1219,14 +1243,14 @@ async function createDOMNodeReference(target, options = {
       const initializedElements = await Promise.all(
         elements.map(async (element) => {
           const instance2 = new DOMNodeReference(element, root, timeout);
-          await instance2[_init]();
+          await instance2[init]();
           return new Proxy(instance2, createProxyHandler());
         })
       );
       return enhanceArray(initializedElements);
     }
     const instance = new DOMNodeReference(target, root, timeout);
-    await instance[_init]();
+    await instance[init]();
     return new Proxy(instance, createProxyHandler());
   } catch (e) {
     throw new Error(e);
@@ -1275,7 +1299,7 @@ function createProxyHandler() {
   };
 }
 
-// src/bindForm.ts
+// src/core/bindForm.ts
 async function bindForm(formId) {
   try {
     const form = await API_default.getRecord("systemforms", formId);

package/dist/constants/eventMapping.d.ts

@@ -0,0 +1,2 @@
+declare const eventMapping: Record<string, keyof HTMLElementEventMap>;
+export default eventMapping;

package/dist/constants/symbols.d.ts

@@ -0,0 +1,13 @@
+export declare const init: unique symbol;
+export declare const destroy: unique symbol;
+export declare const valueSync: unique symbol;
+export declare const dateSync: unique symbol;
+export declare const getElementValue: unique symbol;
+export declare const attachVisibilityController: unique symbol;
+export declare const attachRadioButtons: unique symbol;
+export declare const bindMethods: unique symbol;
+export declare const debounceTime: unique symbol;
+export declare const observers: unique symbol;
+export declare const boundEventListeners: unique symbol;
+export declare const isValidFormElement: unique symbol;
+export declare const registerEventListener: unique symbol;

package/dist/{DOMNodeReference.d.ts → core/DOMNodeReference.d.ts}

@@ -1,54 +1,15 @@
-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;
-declare const _dateSync: unique symbol;
-declare const _getElementValue: unique symbol;
-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;
+import * as s from "@/constants/symbols.js";
 export default class DOMNodeReference {
     target: Element | string;
     logicalName?: string;
     root: Element;
-    private [_debounceTime];
-    private isLoaded;
-    private defaultDisplay;
-    private [_observers];
-    private [_boundEventListeners];
+    protected [s.debounceTime]: number;
+    protected isLoaded: boolean;
+    protected defaultDisplay: string;
+    protected [s.observers]: Array<MutationObserver>;
+    protected [s.boundEventListeners]: Array<IBoundEventListener>;
+    protected isRadio: boolean;
+    protected radioType: RadioType | null;
     /**
      * The value of the element that this node represents
      * stays in syncs with the live DOM elements?.,m  via event handler
@@ -60,7 +21,7 @@ export default class DOMNodeReference {
      * or access properties not available through this class.
      */
     element: HTMLElement;
-    private visibilityController;
+    protected visibilityController: HTMLElement;
     checked: boolean;
     /**
      * Represents the 'yes' option of a boolean radio field.
@@ -81,35 +42,30 @@ export default class DOMNodeReference {
      * Defaults to 'document.body'
      */
     /******/ /******/ constructor(target: Element | string, root: Element | undefined, debounceTime: number);
-    [_init](): Promise<void>;
-    private eventMapping;
+    [s.init](): Promise<void>;
     /**
      * Initializes value synchronization with appropriate event listeners
      * based on element type.
-     * @private
      */
-    private [_valueSync];
-    private [_dateSync];
+    protected [s.valueSync](): Promise<void>;
+    protected [s.isValidFormElement](element: Element): element is FormElement;
+    protected [s.registerEventListener](element: Element, eventType: keyof HTMLElementEventMap, handler: (e: Event) => unknown): void;
+    protected [s.dateSync](element: HTMLInputElement): Promise<void>;
     /**
      * Gets the current value of the element based on its type
-     * @private
+     * @protected
      * @returns Object containing value and optional checked state
      */
-    private [_getElementValue];
-    /**
-     * Updates related radio buttons if this is part of a radio group
-     * @private
-     */
-    private [_updateRadioGroup];
-    private [_attachVisibilityController];
-    private [_attachRadioButtons];
-    private [_bindMethods];
-    private [_destroy];
+    protected [s.getElementValue](): ElementValue;
+    protected [s.attachVisibilityController](): void;
+    protected [s.attachRadioButtons](): Promise<void>;
+    protected [s.bindMethods](): void;
+    protected [s.destroy](): void;
     /**
      * Updates the value and checked state based on element type
      * @public
      */
-    updateValue(): void;
+    updateValue(e?: Event): void;
     /**
      * Sets up an event listener based on the specified event type, executing the specified
      * event handler
@@ -263,13 +219,18 @@ export default class DOMNodeReference {
     configureValidationAndRequirements(isRequired: () => boolean, isValid: () => boolean, fieldDisplayName: string, dependencies: Array<DOMNodeReference>): DOMNodeReference;
     /**
      * Sets up tracking for dependencies using both event listeners and mutation observers.
-     * @private
+     * @protected
      * @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;
+    protected _configDependencyTracking(handler: () => void, dependencies: Array<DOMNodeReference>, options?: {
+        clearValuesOnHide?: boolean;
+        observeVisibility?: boolean;
+        trackInputEvents?: boolean;
+        trackRadioButtons?: boolean;
+    }): void;
     /**
      * Sets the required level for the field by adding or removing the "required-field" class on the label.
      *
@@ -287,4 +248,3 @@ export default class DOMNodeReference {
      */
     onceLoaded(callback: (instance: DOMNodeReference) => any): any;
 }
-export {};

package/dist/{DOMNodeReferenceArray.d.ts → core/DOMNodeReferenceArray.d.ts}

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

package/dist/{bindForm.d.ts → core/bindForm.d.ts}

@@ -1,5 +1,5 @@
 import DOMNodeReference from "./DOMNodeReference.js";
-import { DOMNodeReferenceArray } from "./DOMNodeReferenceArray.js";
+import DOMNodeReferenceArray from "./DOMNodeReferenceArray.js";
 /**
  * @function
  * Get all controls related to the form for manipulating with the

package/dist/core/createDOMNodeReferences.d.ts

@@ -0,0 +1,21 @@
+import DOMNodeReference from "./DOMNodeReference.js";
+import DOMNodeReferenceArray from "./DOMNodeReferenceArray.js";
+export default function createDOMNodeReference<T extends string>(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<T extends string>(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 declare function validateOptions(options: any): void;
+export declare function createProxyHandler(): {
+    get: (target: DOMNodeReference, prop: string | symbol) => any;
+};

package/dist/{errors.d.ts → errors/errors.d.ts}

@@ -1,4 +1,4 @@
-import DOMNodeReference from "./DOMNodeReference.js";
+import DOMNodeReference from "../core/DOMNodeReference.js";
 export declare class DOMNodeInitializationError extends Error {
     constructor(instance: DOMNodeReference, error: string);
 }

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import "./style.css";
-import API from "./API.js";
-import createRef from "./createDOMNodeReferences.js";
-import waitFor from "./waitFor.js";
-import bindForm from "./bindForm.js";
+import API from "./core/API.js";
+import createRef from "./core/createDOMNodeReferences.js";
+import waitFor from "./utils/waitFor.js";
+import bindForm from "./core/bindForm.js";
 export { API, createRef, waitFor, bindForm };

package/dist/managers/ReferenceManager.d.ts

@@ -0,0 +1,5 @@
+import DOMNodeReference from "@/core/DOMNodeReference.js";
+export default abstract class ReferenceManager {
+    static instances: Set<DOMNodeReference>;
+    static getInstance<T>(target: T): DOMNodeReference | undefined;
+}

package/dist/utils/enhanceArray.d.ts

@@ -0,0 +1,3 @@
+import DOMNodeReference from "@/core/DOMNodeReference.js";
+import DOMNodeReferenceArray from "@/core/DOMNodeReferenceArray.js";
+export default function enhanceArray<T extends string>(array: DOMNodeReference[]): DOMNodeReferenceArray & Record<T, DOMNodeReference>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "powerpagestoolkit",
-  "version": "2.7.0",
+  "version": "2.7.101",
   "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/index.js",
   "types": "./dist/index.d.ts",

package/dist/List.d.ts

@@ -1,29 +0,0 @@
-/**
- * so far this whole thing is a moot point
- * Microsoft provides no way to get important specific information
- * about the records represented by each 'row' in a list
- * rendering this effort particularly useless
- *
- * Saving for in case things change in the future and this
- * could be re-factored/extended to provide some usable value
- */
-export declare const _init: symbol;
-/**
- * Provides information about how to target elements in
- * the construction of the list
- */
-interface ListOptions {
-    containerSelector: string;
-    rowSelector: string;
-    cellSelector: string;
-}
-interface ListItem extends Array<Element> {
-}
-export default class List {
-    [x: symbol]: () => Promise<List>;
-    items: ListItem[];
-    private options;
-    private container;
-    constructor(options?: Partial<ListOptions>);
-}
-export {};

package/dist/createDOMNodeReferences.d.ts

@@ -1,36 +0,0 @@
-import { DOMNodeReferenceArray } from "./DOMNodeReferenceArray.js";
-import DOMNodeReference from "./DOMNodeReference.js";
-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?: 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 {};