powerpagestoolkit 2.5.409 → 2.5.4111

package/README.md

@@ -19,7 +19,7 @@ A TypeScript/JavaScript utility package for seamless DOM manipulation and DataVe
 npm install powerpagestoolkit
 ```
 
-## Core Modules
+# Core Modules
 
 ### DOMNodeReference
 
@@ -27,13 +27,28 @@ A powerful class for managing DOM elements with automatic value synchronization
 
 #### 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,113 @@ 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
+```
+
+_Example 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.
+
+_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
+): DOMNodeReference; /* instance of this is returned for optional
+ method chaining */
+```
+
+_Example implementation:_
+
 ```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();
+
+// Clear the value for both the instance and the target element
+node.clearValue()
+
+/****/ 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
@@ -153,9 +220,9 @@ node.addTooltip(
 
 ### 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", {
@@ -215,18 +282,10 @@ node.configureConditionalRendering(
 
 3. Use TypeScript for better type safety and IntelliSense support.
 
-4. Handle loading states:
-
-```typescript
-node.onceLoaded((instance) => {
-  // Safe to manipulate the element here
-});
-```
-
-5. Use proper error handling with API operations:
+4. Use proper error handling with API operations:
 
 ```typescript
-await API.createRecord(/*...*/)
+/* optionally await */ API.createRecord(/*...*/)
   .then((recordId) => {})
   .catch((error) => {
     // handle your errors appropriately
@@ -244,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

@@ -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>;
@@ -84,7 +80,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]
      */
@@ -109,7 +105,7 @@ export default class DOMNodeReference {
      * @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]
@@ -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.
    */
   /******/
   /******/
@@ -442,7 +441,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]
    */
@@ -494,7 +493,7 @@ var DOMNodeReference = class _DOMNodeReference {
    * @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) {
@@ -535,14 +534,14 @@ var DOMNodeReference = class _DOMNodeReference {
         if (childInputs.length > 0) {
           const clearPromises = childInputs.map(async (input) => {
             const inputRef = await createDOMNodeReference(input, false);
-            return inputRef.clearValues();
+            return inputRef.clearValue();
           });
           await Promise.all(clearPromises);
         }
       }
       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 }),
@@ -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.clearValue();
         }
-      });
-      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.4111",
   "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",