powerpagestoolkit 2.5.409 → 2.5.411

package/README.md

@@ -19,21 +19,36 @@ A TypeScript/JavaScript utility package for seamless DOM manipulation and DataVe
 npm install powerpagestoolkit
 ```
 
-## Core Modules
+# Core Modules
 
-### DOMNodeReference
+- ### DOMNodeReference
 
 A powerful class for managing DOM elements with automatic value synchronization and event handling.
 
 #### Basic Usage
 
+DOMNodeReferences are instantiated with the help of the following factory function
+
+```typescript
+createRef(
+  target: HTMLElement | string, /* You can target an HTMLElement directly,
+  or use standard querySelector syntax */
+  multiple: (() => boolean) | boolean = false /* are you targeting a single
+  element, or multiple? true = multiple. Default is false (single) */
+): Promise<DOMNodeReference | DOMNodeReferenceArray>;
+```
+
+Import the utility function for creating DOMNodeReference(s)
+
 ```typescript
 import { createRef } from "powerpagestoolkit";
+```
 
-// Both methods support standard querySelector syntax:
+Instantiate one, or multiple instances of a DOMNodeReference
 
+```typescript
 // Create a single reference
-const node = await createRef("#myElement");
+const node = await createRef("#myElement", false);
 
 // Create multiple references
 const nodes = await createRef(".my-class", true);
@@ -57,14 +72,16 @@ const nodes = await createRef(".my-class", true);
 
 ```typescript
 // Add event listener with proper 'this' context
+// uses standard eventListener API, and so supports all DOM events
 node.on("change", function (e) {
   console.log("Current value:", this.value);
 });
 
-// Wait for element to be loaded
-node.onceLoaded((instance) => {
-  console.log("Element ready:", instance.element);
+node.on("click", function (e) {
+  console.log(this, " has been clicked");
 });
+
+...
 ```
 
 ##### Visibility Control
@@ -73,63 +90,108 @@ node.onceLoaded((instance) => {
 // Basic visibility
 node.hide();
 node.show();
+```
+
+##### 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
 
-// Advanced conditional rendering
+- Method Signature
+
+```typescript
+DOMNodeReference.configureConditionalRendering(
+    condition: () => boolean,
+    dependencies?: Array<DOMNodeReference>,
+    clearValuesOnHide: boolean = true
+  ): DOMNodeReference
+```
+
+- Method Implementation
+
+```typescript
 node.configureConditionalRendering(
   // Function to evaluate wether this node should be visible or not
   function () {
-    return otherNode.value === "expected";
+    return otherNode.value === "some value";
   },
-  [otherNode] // Dependency array | if the values or visibility of these change, the function is re-evaluated
+  [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 */
 );
 ```
 
 ##### Validation and Requirements
 
+This utility enhances PowerPages forms by adding dynamic field validation and conditional requirements based on other field values.
+
+```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
+): DOMNodeReference; /* instance of this is returned for optional
+ method chaining */
+```
+
+- Here's a practical example showing how to make a field required only when a "Yes" radio button is selected:
+
 ```typescript
 node.configureValidationAndRequirements(
-  // Function to evaluate if this field should be required
-  function () {
-    return dependentNode.yesRadio?.checked ?? false;
-  },
-  // Function to evaluate if the data in this field is valid
+  // 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 !== "";
   },
-  "Field Display Name", // the name that will be displayed along side a validation failure message
-  [dependentNode] // Dependency array | if the requirement level of these change, this element is re-evaluated
+
+  "Contact Phone", // Shows in error message: "Contact Phone is required"
+
+  [dependentNode] // Revalidate when dependentNode changes
 );
 ```
 
 ##### Element Manipulation
 
 ```typescript
-// Value management
-node.setValue("new value"); // set a static value
+/****/ Value management /****/
+
+// set a static value
+node.setValue("new value");
+
 // or set a value by using some sort of logic
 node.setValue(() => {
   if (true) {
     return "value";
   } else return "default";
 });
-node.updateValue(); // Sync with DOM
 
-// Content manipulation
+// Sync with DOM
+node.updateValue();
+
+/****/ Content manipulation /****/
+
 node.setInnerHTML("<span>New content</span>");
 node.append(childElement);
 node.prepend(headerElement);
 node.after(siblingElement);
 node.before(labelElement);
 
-// Styling
+/****/ Styling /****/
+
 node.setStyle({
   display: "block",
   color: "red",
 });
 
-// State management
+/****/ State management /****/
+
 node.disable();
 node.enable();
+
 ```
 
 ##### Label and Tooltip Management
@@ -151,7 +213,7 @@ node.addTooltip(
 );
 ```
 
-### DataVerse API
+- ### DataVerse API
 
 Type-safe wrapper for DataVerse API operations.
 

package/dist/DOMNodeReference.d.ts

@@ -6,14 +6,12 @@ export default class DOMNodeReference {
     /**
      * The value of the element that this node represents
      * stays in syncs with the live DOM elements?.,m  via event handler
-     * @type {any}
      */
     value: any;
     /**
      * The element targeted when instantiating DOMNodeReference.
      * Made available in order to perform normal DOM traversal,
      * or access properties not available through this class.
-     * @property {HTMLElement | null}
      */
     element: Element;
     private visibilityController;
@@ -22,19 +20,17 @@ export default class DOMNodeReference {
      * Represents the 'yes' option of a boolean radio field.
      * This property is only available when the parent node
      * is a main field for a boolean radio input.
-     * @property {DOMNodeReferenceProxy | null}
      */
     yesRadio?: DOMNodeReference | null;
     /**
      * Represents the 'no' option of a boolean radio field.
      * This property is only available when the parent node
      * is a main field for a boolean radio input.
-     * @property {DOMNodeReferenceProxy | null}
      */
     noRadio?: DOMNodeReference | null;
     /**
      * Creates an instance of DOMNodeReference.
-     * @param {string} target - The CSS selector to find the desired DOM element.
+     * @param target - The CSS selector to find the desired DOM element.
      */
     /******/ /******/ constructor(target: HTMLElement | string);
     [_init](): Promise<void>;
@@ -206,10 +202,13 @@ export default class DOMNodeReference {
      */
     configureValidationAndRequirements(isRequired: () => boolean, isValid: () => boolean, fieldDisplayName: string, dependencies: Array<DOMNodeReference>): DOMNodeReference;
     /**
-     * Sets up tracking for dependent fields using both event listeners and mutation observers.
+     * 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
      */
-    private _setupDependencyTracking;
+    private _configDependencyTracking;
     /**
      * Sets the required level for the field by adding or removing the "required-field" class on the label.
      *

package/dist/bundle.js

@@ -237,12 +237,11 @@ var DOMNodeReference = class _DOMNodeReference {
   /**
    * The value of the element that this node represents
    * stays in syncs with the live DOM elements?.,m  via event handler
-   * @type {any}
    */
   value;
   /**
    * Creates an instance of DOMNodeReference.
-   * @param {string} target - The CSS selector to find the desired DOM element.
+   * @param target - The CSS selector to find the desired DOM element.
    */
   /******/
   /******/
@@ -710,40 +709,16 @@ var DOMNodeReference = class _DOMNodeReference {
         );
         return this;
       }
-      dependencies.forEach((node) => {
-        if (!node || !(node instanceof _DOMNodeReference)) {
-          throw new TypeError(
-            "Each dependency must be a valid DOMNodeReference instance"
-          );
+      this._configDependencyTracking(
+        () => this.toggleVisibility(condition()),
+        dependencies,
+        {
+          clearValuesOnHide,
+          observeVisibility: true,
+          trackInputEvents: false,
+          trackRadioButtons: false
         }
-        const handleChange = () => {
-          try {
-            this.toggleVisibility(condition());
-            if (condition() === false && clearValuesOnHide) {
-              this.clearValues();
-            }
-          } catch (error) {
-            console.error("Error in change handler:", error);
-          }
-        };
-        node.on("change", handleChange);
-        const observer = new MutationObserver(() => {
-          try {
-            const display = window.getComputedStyle(
-              node.visibilityController
-            ).display;
-            this.toggleVisibility(display !== "none" && condition());
-          } catch (error) {
-            0;
-            console.error("Error in mutation observer:", error);
-            observer.disconnect();
-          }
-        });
-        observer.observe(node.visibilityController, {
-          attributes: true,
-          attributeFilter: ["style"]
-        });
-      });
+      );
       return this;
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
@@ -792,7 +767,10 @@ var DOMNodeReference = class _DOMNodeReference {
       Object.assign(newValidator, validatorConfig);
       Page_Validators.push(newValidator);
       this.setRequiredLevel(isRequired());
-      this._setupDependencyTracking(isRequired, dependencies);
+      this._configDependencyTracking(
+        () => this.setRequiredLevel(isRequired()),
+        dependencies
+      );
     } catch (error) {
       throw new ValidationConfigError(
         this,
@@ -802,35 +780,64 @@ var DOMNodeReference = class _DOMNodeReference {
     return this;
   }
   /**
-   * Sets up tracking for dependent fields using both event listeners and mutation observers.
+   * Sets up tracking for dependencies using both event listeners and mutation observers.
    * @private
-   */
-  _setupDependencyTracking(isRequired, dependencies) {
-    if (dependencies.length === 0) {
+   * @param handler - The function to execute when dependencies change
+   * @param dependencies - Array of dependent DOM nodes to track
+   * @param options - Additional configuration options
+   */
+  _configDependencyTracking(handler, dependencies, options = {
+    clearValuesOnHide: false,
+    observeVisibility: true,
+    trackInputEvents: true,
+    trackRadioButtons: true
+  }) {
+    const {
+      clearValuesOnHide = false,
+      observeVisibility = true,
+      trackInputEvents = true,
+      trackRadioButtons = true
+    } = options;
+    if (!dependencies?.length) {
       console.warn(
-        `powerpagestoolkit: No dependencies specified for ${this.element.id}. Include all referenced nodes in the dependency array for proper validation.`
+        `powerpagestoolkit: No dependencies specified for ${this.element.id}. Include all referenced nodes in the dependency array for proper tracking.`
       );
       return;
     }
     dependencies.forEach((dep) => {
-      dep.on("change", () => this.setRequiredLevel(isRequired(this)));
-      dep.on("input", () => this.setRequiredLevel(isRequired(this)));
-      const observer = new MutationObserver(() => {
-        const display = window.getComputedStyle(
-          dep.visibilityController
-        ).display;
-        if (display !== "none") {
-          this.setRequiredLevel(isRequired(this));
+      if (!dep || !(dep instanceof _DOMNodeReference)) {
+        throw new TypeError(
+          "Each dependency must be a valid DOMNodeReference instance"
+        );
+      }
+      const handleChange = () => {
+        handler();
+        if (clearValuesOnHide && window.getComputedStyle(this.visibilityController).display === "none") {
+          this.clearValues();
         }
-      });
-      observer.observe(dep.visibilityController, {
-        attributes: true,
-        attributeFilter: ["style"],
-        subtree: false
-      });
-      if (dep.yesRadio || dep.noRadio) {
+      };
+      dep.on("change", handleChange);
+      if (trackInputEvents) {
+        dep.on("input", handleChange);
+      }
+      if (observeVisibility) {
+        const observer = new MutationObserver(() => {
+          const display = window.getComputedStyle(
+            dep.visibilityController
+          ).display;
+          if (display !== "none") {
+            handler();
+          }
+        });
+        observer.observe(dep.visibilityController, {
+          attributes: true,
+          attributeFilter: ["style"],
+          subtree: false
+        });
+      }
+      if (trackRadioButtons && (dep.yesRadio || dep.noRadio)) {
         [dep.yesRadio, dep.noRadio].forEach((radio) => {
-          radio?.on("change", () => this.setRequiredLevel(isRequired(this)));
+          radio?.on("change", handleChange);
         });
       }
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "powerpagestoolkit",
-  "version": "2.5.409",
+  "version": "2.5.411",
   "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",