powerpagestoolkit 2.5.4111 → 2.5.4212

package/README.md

@@ -99,23 +99,25 @@ Out of the box, Microsoft does not provide PowerPages developers the ability to
 _Method signature:_
 
 ```typescript
-DOMNodeReference.configureConditionalRendering(
+configureConditionalRendering(
     condition: () => boolean,
     dependencies?: Array<DOMNodeReference>,
     clearValuesOnHide: boolean = true
-  ): DOMNodeReference
+  ): DOMNodeReference /* Instance of this returned
+  for optional method chaining */
 ```
 
 _Example implementation:_
 
 ```typescript
 node.configureConditionalRendering(
-  // Function to evaluate wether this node should be visible or not
-  function () {
+  function () // Function to evaluate wether this node should be visible or not
+  {
     return otherNode.value === "some value";
   },
   [otherNode] /* Dependency array | if the values or visibility of these
   change, the function is re-evaluated */,
+
   true /* should the values in the targeted elements (this.element)
   be cleared if this node is hidden? Default = true */
 );
@@ -128,12 +130,11 @@ This utility enhances PowerPages forms by adding dynamic field validation and co
 _Method signature:_
 
 ```typescript
-// Core method for setting up validation
-function configureValidationAndRequirements(
-  isRequired: () => boolean, // Determines if field is required
-  isValid: () => boolean, // Validates field content
-  fieldDisplayName: string, // User-facing field name for error messages
-  dependencies: DOMNodeReference[] // Fields that trigger validation checks
+configureValidationAndRequirements(
+  isRequired: () => boolean,
+  isValid: () => boolean,
+  fieldDisplayName: string,
+  dependencies: DOMNodeReference[]
 ): DOMNodeReference; /* instance of this is returned for optional
  method chaining */
 ```
@@ -218,6 +219,20 @@ node.addTooltip(
 );
 ```
 
+_Example:_
+
+```typescript
+import { createRef } from "powerpagestoolkit";
+
+const title = await createRef("h1");
+
+title.setInnerHTML("Hello World");
+title.addTooltip("This is an Example of a tooltip!", { color: "red" });
+```
+
+![Example](./assets//infoIconExample.gif)
+
+
 ### 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/DOMNodeReference.d.ts

@@ -3,6 +3,8 @@ export default class DOMNodeReference {
     target: HTMLElement | string;
     private isLoaded;
     private defaultDisplay;
+    private observers;
+    private boundEventListeners;
     /**
      * The value of the element that this node represents
      * stays in syncs with the live DOM elements?.,m  via event handler
@@ -13,7 +15,7 @@ export default class DOMNodeReference {
      * Made available in order to perform normal DOM traversal,
      * or access properties not available through this class.
      */
-    element: Element;
+    element: HTMLElement;
     private visibilityController;
     checked: boolean;
     /**
@@ -41,11 +43,6 @@ export default class DOMNodeReference {
      */
     private _initValueSync;
     private _initDateSync;
-    /**
-     * Updates the value and checked state based on element type
-     * @public
-     */
-    updateValue(): void;
     /**
      * Gets the current value of the element based on its type
      * @private
@@ -59,6 +56,13 @@ export default class DOMNodeReference {
     private _updateRadioGroup;
     private _attachVisibilityController;
     private _attachRadioButtons;
+    private _bindMethods;
+    private _destroy;
+    /**
+     * Updates the value and checked state based on element type
+     * @public
+     */
+    updateValue(): void;
     /**
      * Sets up an event listener based on the specified event type, executing the specified
      * event handler
@@ -67,7 +71,7 @@ export default class DOMNodeReference {
      * specified event occurs.
      * @returns - Instance of this [provides option to method chain]
      */
-    on(eventType: string, eventHandler: (e: Event) => void): DOMNodeReference;
+    on(eventType: keyof HTMLElementEventMap, eventHandler: (e: Event) => void): DOMNodeReference;
     /**
      * Hides the element by setting its display style to "none".
      * @returns - Instance of this [provides option to method chain]
@@ -100,7 +104,8 @@ export default class DOMNodeReference {
     disable(): DOMNodeReference;
     /**
      * Clears all values and states of the element.
-     * Handles different input types appropriately.
+     * Handles different input types appropriately, and can be called
+     * on an element containing N child inputs to clear all
      *
      * @returns - Instance of this [provides option to method chain]
      * @throws If clearing values fails
@@ -180,25 +185,25 @@ export default class DOMNodeReference {
      * Configures conditional rendering for the target element based on a condition
      * and the visibility of one or more trigger elements.
      *
-     * @param {() => boolean} condition - A function that returns a boolean to determine
+     * @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 {Array<DOMNodeReference>} [dependencies] - An array of `DOMNodeReference` instances. Event listeners are
+     * @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 {ConditionalRenderingError} When there's an error in setting up conditional rendering
-     * @returns {DOMNodeReference} - 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 {() => boolean} isRequired - Function determining if field is required
-     * @param {() => boolean} isValid - Function validating field input
-     * @param {string} fieldDisplayName - Display name for error messages
-     * @param {Array<DOMNodeReference>} dependencies - Fields that trigger requirement/validation updates
-     * @returns {DOMNodeReference} Instance of this
-     * @throws {ValidationConfigError} If validation setup fails
+     * @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;
     /**
@@ -212,7 +217,7 @@ export default class DOMNodeReference {
     /**
      * Sets the required level for the field by adding or removing the "required-field" class on the label.
      *
-     * @param {Function | boolean} 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]
      */
@@ -221,7 +226,8 @@ export default 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 {Function} 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/bundle.js

@@ -234,6 +234,8 @@ var DOMNodeReference = class _DOMNodeReference {
   target;
   isLoaded;
   defaultDisplay;
+  observers;
+  boundEventListeners;
   /**
    * The value of the element that this node represents
    * stays in syncs with the live DOM elements?.,m  via event handler
@@ -250,7 +252,9 @@ var DOMNodeReference = class _DOMNodeReference {
     this.isLoaded = false;
     this.defaultDisplay = "";
     this.value = null;
-    this.updateValue = this.updateValue.bind(this);
+    this.observers = [];
+    this.boundEventListeners = [];
+    this._bindMethods();
   }
   async [_init]() {
     try {
@@ -265,9 +269,23 @@ var DOMNodeReference = class _DOMNodeReference {
       this._initValueSync();
       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();
+            observer.disconnect();
+            break;
+          }
+        }
+      });
+      observer.observe(document.body, {
+        childList: true,
+        subtree: true
+      });
       this.isLoaded = true;
-    } catch (e) {
-      throw new DOMNodeInitializationError(this, e);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new DOMNodeInitializationError(this, errorMessage);
     }
   }
   /**
@@ -297,6 +315,13 @@ var DOMNodeReference = class _DOMNodeReference {
         eventType = "input";
       }
       this.element.addEventListener(eventType, this.updateValue);
+      const _element = this.element;
+      const _updateValue = this.updateValue;
+      this.boundEventListeners.push({
+        element: _element,
+        handler: _updateValue,
+        event: eventType
+      });
       if (this.element instanceof HTMLInputElement && this.element.dataset.type === "date") {
         await this._initDateSync(this.element);
       }
@@ -314,18 +339,12 @@ var DOMNodeReference = class _DOMNodeReference {
     }
     const dateNode = await waitFor("[data-date-format]", parentElement);
     dateNode.addEventListener("select", this.updateValue);
-  }
-  /**
-   * Updates the value and checked state based on element type
-   * @public
-   */
-  updateValue() {
-    const elementValue = this._getElementValue();
-    this.value = elementValue.value;
-    if (elementValue.checked !== void 0) {
-      this.checked = elementValue.checked;
-    }
-    this._updateRadioGroup();
+    const _handler = this.updateValue;
+    this.boundEventListeners.push({
+      element: dateNode,
+      handler: _handler,
+      event: "select"
+    });
   }
   /**
    * Gets the current value of the element based on its type
@@ -401,6 +420,44 @@ var DOMNodeReference = class _DOMNodeReference {
     this.yesRadio = await createDOMNodeReference(`#${this.element.id}_1`);
     this.noRadio = await createDOMNodeReference(`#${this.element.id}_0`);
   }
+  _bindMethods() {
+    for (const key of Object.getOwnPropertyNames(Object.getPrototypeOf(this))) {
+      const value = this[key];
+      if (key !== "constructor" && typeof value === "function") {
+        this[key] = value.bind(this);
+      }
+    }
+  }
+  _destroy() {
+    if (this.boundEventListeners.length > 0) {
+      this.boundEventListeners.forEach((binding) => {
+        binding.element?.removeEventListener(binding.event, binding.handler);
+      });
+    }
+    if (this.observers.length > 0) {
+      this.observers.forEach((observer) => {
+        observer.disconnect();
+      });
+    }
+    this.yesRadio?._destroy();
+    this.noRadio?._destroy();
+    this.yesRadio = null;
+    this.noRadio = null;
+    this.isLoaded = false;
+    this.value = null;
+  }
+  /**
+   * Updates the value and checked state based on element type
+   * @public
+   */
+  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
    * event handler
@@ -410,17 +467,19 @@ var DOMNodeReference = class _DOMNodeReference {
    * @returns - Instance of this [provides option to method chain]
    */
   on(eventType, eventHandler) {
-    if (typeof eventType !== "string") {
-      throw new Error(
-        `Argument "eventType" must be of type "string". Received: ${typeof eventType}`
-      );
-    }
     if (typeof eventHandler !== "function") {
       throw new Error(
         `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
+    });
     return this;
   }
   /**
@@ -479,16 +538,18 @@ var DOMNodeReference = class _DOMNodeReference {
   disable() {
     try {
       this.element.disabled = true;
-    } catch (e) {
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
       throw new Error(
-        `There was an error trying to disable the target: ${this.target}`
+        `There was an error trying to disable the target: ${this.target}: "${errorMessage}"`
       );
     }
     return this;
   }
   /**
    * Clears all values and states of the element.
-   * Handles different input types appropriately.
+   * Handles different input types appropriately, and can be called
+   * on an element containing N child inputs to clear all
    *
    * @returns - Instance of this [provides option to method chain]
    * @throws If clearing values fails
@@ -532,11 +593,11 @@ var DOMNodeReference = class _DOMNodeReference {
           this.element.querySelectorAll("input, select, textarea")
         );
         if (childInputs.length > 0) {
-          const clearPromises = childInputs.map(async (input) => {
+          const promises = childInputs.map(async (input) => {
             const inputRef = await createDOMNodeReference(input, false);
             return inputRef.clearValue();
           });
-          await Promise.all(clearPromises);
+          await Promise.all(promises);
         }
       }
       if (this.yesRadio instanceof _DOMNodeReference && this.noRadio instanceof _DOMNodeReference) {
@@ -686,14 +747,14 @@ var DOMNodeReference = class _DOMNodeReference {
    * Configures conditional rendering for the target element based on a condition
    * and the visibility of one or more trigger elements.
    *
-   * @param {() => boolean} condition - A function that returns a boolean to determine
+   * @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 {Array<DOMNodeReference>} [dependencies] - An array of `DOMNodeReference` instances. Event listeners are
+   * @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 {ConditionalRenderingError} When there's an error in setting up conditional rendering
-   * @returns {DOMNodeReference} - 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 {
@@ -728,12 +789,12 @@ var DOMNodeReference = class _DOMNodeReference {
   /**
    * Sets up validation and requirement rules for the field with enhanced error handling and dynamic updates.
    *
-   * @param {() => boolean} isRequired - Function determining if field is required
-   * @param {() => boolean} isValid - Function validating field input
-   * @param {string} fieldDisplayName - Display name for error messages
-   * @param {Array<DOMNodeReference>} dependencies - Fields that trigger requirement/validation updates
-   * @returns {DOMNodeReference} Instance of this
-   * @throws {ValidationConfigError} If validation setup fails
+   * @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()) {
@@ -834,6 +895,7 @@ var DOMNodeReference = class _DOMNodeReference {
           attributeFilter: ["style"],
           subtree: false
         });
+        this.observers.push(observer);
       }
       if (trackRadioButtons && (dep.yesRadio || dep.noRadio)) {
         [dep.yesRadio, dep.noRadio].forEach((radio) => {
@@ -845,7 +907,7 @@ var DOMNodeReference = class _DOMNodeReference {
   /**
    * Sets the required level for the field by adding or removing the "required-field" class on the label.
    *
-   * @param {Function | boolean} 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]
    */
@@ -862,7 +924,8 @@ 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 {Function} 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) {
     if (this.isLoaded) {
@@ -884,6 +947,7 @@ var DOMNodeReference = class _DOMNodeReference {
       subtree: true,
       childList: true
     });
+    this.observers.push(observer);
   }
 };
 
@@ -932,10 +996,21 @@ function createProxyHandler() {
   };
 }
 function enhanceArray(array) {
-  const enhanced = array;
-  enhanced.hideAll = () => enhanced.forEach((instance) => instance.hide());
-  enhanced.showAll = () => enhanced.forEach((instance) => instance.show());
-  return enhanced;
+  Object.defineProperties(array, {
+    hideAll: {
+      value: function() {
+        this.forEach((instance) => instance.hide());
+        return this;
+      }
+    },
+    showAll: {
+      value: function() {
+        this.forEach((instance) => instance.show());
+        return this;
+      }
+    }
+  });
+  return array;
 }
 export {
   API_default as API,

package/dist/createDOMNodeReferences.d.ts

@@ -6,4 +6,4 @@ import DOMNodeReference from "./DOMNodeReference.js";
  * @param multiple Should this call return an array of instantiated references, or just a single? Defaults to false, returning a single instance
  * @returns  A promise that resolves to a Proxy of the initialized DOMNodeReference instance.
  */
-export default function createDOMNodeReference(target: HTMLElement | string, multiple?: (() => boolean) | boolean): Promise<DOMNodeReference | DOMNodeReferenceArray>;
+export default function createDOMNodeReference(target: HTMLElement | string, multiple?: (() => boolean) | boolean): Promise<DOMNodeReference | DOMNodeReference[]>;

package/dist/waitFor.d.ts

@@ -4,4 +4,4 @@
  * @param root optional parameter to replace document as the root from which to perform the node search
  * @returns
  */
-export default function waitFor(target: HTMLElement | string, root?: Element | Document): Promise<Element>;
+export default function waitFor(target: HTMLElement | string, root?: HTMLElement | Document): Promise<HTMLElement>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "powerpagestoolkit",
-  "version": "2.5.4111",
+  "version": "2.5.4212",
   "description": "Reference, manipulate, and engage with Power Pages sites through the nodes in the DOM; use a variety of custom methods that allow customizing your power pages site quicker and easier.  ",
   "main": "./dist/bundle.js",
   "types": "./dist/index.d.ts",
@@ -58,7 +58,8 @@
   "files": [
     "dist/bundle.js",
     "dist/bundle.css",
-    "dist/**/*.d.ts"
+    "dist/**/*.d.ts",
+    "assets/**"
   ],
   "exports": {
     ".": {