powerpagestoolkit 2.5.411 → 2.5.4211

package/README.md

@@ -21,7 +21,7 @@ npm install powerpagestoolkit
 
 # Core Modules
 
-- ### DOMNodeReference
+### DOMNodeReference
 
 A powerful class for managing DOM elements with automatic value synchronization and event handling.
 
@@ -92,11 +92,11 @@ node.hide();
 node.show();
 ```
 
-##### Advanced conditional rendering
+**_Advanced conditional rendering_**
 
 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
 
-- Method Signature
+_Method signature:_
 
 ```typescript
 DOMNodeReference.configureConditionalRendering(
@@ -106,7 +106,7 @@ DOMNodeReference.configureConditionalRendering(
   ): DOMNodeReference
 ```
 
-- Method Implementation
+_Example implementation:_
 
 ```typescript
 node.configureConditionalRendering(
@@ -125,6 +125,8 @@ node.configureConditionalRendering(
 
 This utility enhances PowerPages forms by adding dynamic field validation and conditional requirements based on other field values.
 
+_Method signature:_
+
 ```typescript
 // Core method for setting up validation
 function configureValidationAndRequirements(
@@ -136,7 +138,7 @@ function configureValidationAndRequirements(
  method chaining */
 ```
 
-- Here's a practical example showing how to make a field required only when a "Yes" radio button is selected:
+_Example implementation:_
 
 ```typescript
 node.configureValidationAndRequirements(
@@ -172,6 +174,9 @@ node.setValue(() => {
 // Sync with DOM
 node.updateValue();
 
+// Clear the value for both the instance and the target element
+node.clearValue()
+
 /****/ Content manipulation /****/
 
 node.setInnerHTML("<span>New content</span>");
@@ -213,11 +218,11 @@ node.addTooltip(
 );
 ```
 
-- ### DataVerse API
+### DataVerse API
 
-Type-safe wrapper for DataVerse API operations.
+Perform secure API calls to DataVerse from your PowerPages site. This method implements the shell deferred token to send requests with `__RequestVerificationToken`
 
-#### Create Record
+#### Create Records
 
 ```typescript
 await API.createRecord("accounts", {
@@ -277,18 +282,10 @@ node.configureConditionalRendering(
 
 3. Use TypeScript for better type safety and IntelliSense support.
 
-4. Handle loading states:
+4. Use proper error handling with API operations:
 
 ```typescript
-node.onceLoaded((instance) => {
-  // Safe to manipulate the element here
-});
-```
-
-5. Use proper error handling with API operations:
-
-```typescript
-await API.createRecord(/*...*/)
+/* optionally await */ API.createRecord(/*...*/)
   .then((recordId) => {})
   .catch((error) => {
     // handle your errors appropriately
@@ -306,3 +303,7 @@ Contributions are welcome, feel free to create a pull request with enhancements.
 ## License
 
 This project is licensed under the AGPL-3.0 License - see the [LICENSE](LICENSE) file for details.
+
+## Funding
+
+If you like this project, found it useful, or would like to help support the long-term support of this package, please feel free to contribute via GitHub Sponsors: [Keaton-Brewster](https://github.com/sponsors/Keaton-Brewster)

package/dist/DOMNodeReference.d.ts

@@ -13,7 +13,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 +41,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 +54,12 @@ export default class DOMNodeReference {
     private _updateRadioGroup;
     private _attachVisibilityController;
     private _attachRadioButtons;
+    private _bindMethods;
+    /**
+     * 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
@@ -80,7 +81,7 @@ export default class DOMNodeReference {
     show(): DOMNodeReference;
     /**
      *
-     * @param {function(instance: DOMNodeReference): boolean | boolean} shouldShow - Either a function that returns true or false,
+     * @param shouldShow - Either a function that returns true or false,
      * or a natural boolean to determine the visibility of this
      * @returns - Instance of this [provides option to method chain]
      */
@@ -100,12 +101,13 @@ 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
      */
-    clearValues(): Promise<DOMNodeReference>;
+    clearValue(): Promise<DOMNodeReference>;
     /**
      * Enables the element so that users can input data
      * @returns - Instance of this [provides option to method chain]
@@ -180,25 +182,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 +214,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 +223,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

@@ -250,7 +250,7 @@ var DOMNodeReference = class _DOMNodeReference {
     this.isLoaded = false;
     this.defaultDisplay = "";
     this.value = null;
-    this.updateValue = this.updateValue.bind(this);
+    this._bindMethods();
   }
   async [_init]() {
     try {
@@ -266,8 +266,9 @@ var DOMNodeReference = class _DOMNodeReference {
       this._attachVisibilityController();
       this.defaultDisplay = this.visibilityController.style.display;
       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);
     }
   }
   /**
@@ -315,18 +316,6 @@ 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();
-  }
   /**
    * Gets the current value of the element based on its type
    * @private
@@ -401,6 +390,26 @@ 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);
+      }
+    }
+  }
+  /**
+   * 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
@@ -441,7 +450,7 @@ var DOMNodeReference = class _DOMNodeReference {
   }
   /**
    *
-   * @param {function(instance: DOMNodeReference): boolean | boolean} shouldShow - Either a function that returns true or false,
+   * @param shouldShow - Either a function that returns true or false,
    * or a natural boolean to determine the visibility of this
    * @returns - Instance of this [provides option to method chain]
    */
@@ -479,21 +488,23 @@ 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
    */
-  async clearValues() {
+  async clearValue() {
     try {
       const element = this.element;
       if (element instanceof HTMLInputElement) {
@@ -532,16 +543,16 @@ 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.clearValues();
+            return inputRef.clearValue();
           });
-          await Promise.all(clearPromises);
+          await Promise.all(promises);
         }
       }
       if (this.yesRadio instanceof _DOMNodeReference && this.noRadio instanceof _DOMNodeReference) {
-        await this.yesRadio.clearValues();
-        await this.noRadio.clearValues();
+        await this.yesRadio.clearValue();
+        await this.noRadio.clearValue();
       }
       const events = [
         new Event("input", { bubbles: true }),
@@ -686,14 +697,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 +739,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()) {
@@ -813,7 +824,7 @@ var DOMNodeReference = class _DOMNodeReference {
       const handleChange = () => {
         handler();
         if (clearValuesOnHide && window.getComputedStyle(this.visibilityController).display === "none") {
-          this.clearValues();
+          this.clearValue();
         }
       };
       dep.on("change", handleChange);
@@ -845,7 +856,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 +873,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) {

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.411",
+  "version": "2.5.4211",
   "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",