powerpagestoolkit 2.5.0 → 2.5.2

package/README.md

@@ -154,14 +154,14 @@ Type-safe wrapper for DataVerse API operations.
 #### Create Record
 
 ```typescript
-const recordId = await API.createRecord("accounts", {
-  name: "New Account",
-  type: "Customer",
+await API.createRecord("accounts", {
+  name: "Gypsum LLC",
+  type: "Vendor",
 })
-  .then(() => {
+  .then((recordId) => {
     console.log("Created record:", recordId);
   })
-  .catch(() => {
+  .catch((error) => {
     console.error("Creation failed:", error);
   });
 ```
@@ -222,11 +222,11 @@ node.onceLoaded((instance) => {
 5. Use proper error handling with API operations:
 
 ```typescript
-try {
-  await API.createRecord(/*...*/);
-} catch (error) {
-  // Handle error appropriately
-}
+await API.createRecord(/*...*/)
+  .then((recordId) => {})
+  .catch((error) => {
+    // handle your errors appropriately
+  });
 ```
 
 ## TypeScript Support
@@ -239,4 +239,4 @@ Contributions are welcome, feel free to create a pull request with enhancements.
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+This project is licensed under the AGPL-3.0 License - see the [LICENSE](LICENSE) file for details.

package/dist/DOMNodeReference.d.ts

@@ -46,7 +46,7 @@ export declare const _init: unique symbol;
      * Sets up an event listener based on the specified event type, executing the specified
      * event handler
      * @param {string} eventType - The DOM event to watch for
-     * @param {(this: DOMNodeReference, e: Event) => void} eventHandler - The callback function that runs when the
+     * @param {(e: Event) => void} eventHandler - The callback function that runs when the
      * specified event occurs
      * @returns - Instance of this
      */
@@ -63,11 +63,11 @@ export declare const _init: unique symbol;
     show(): DOMNodeReference;
     /**
      *
-     * @param {function(this: DOMNodeReference): boolean | boolean} shouldShow - Either a function that returns true or false,
+     * @param {function(instance: DOMNodeReference): boolean | boolean} shouldShow - Either a function that returns true or false,
      * or a natural boolean to determine the visibility of this
      * @returns - Instance of this
      */
-    toggleVisibility(shouldShow: Function | boolean): DOMNodeReference;
+    toggleVisibility(shouldShow: ((instance: DOMNodeReference) => boolean) | boolean): DOMNodeReference;
     /**
      * Sets the value of the HTML element.
      * @param {(() => any) | any} value - The value to set for the HTML element.
@@ -156,28 +156,35 @@ export declare const _init: unique symbol;
      */
     uncheckRadios(): DOMNodeReference;
     /**
-     * Configures conditional rendering for the target element based on a condition
-     * and the visibility of one or more trigger elements.
+    * 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
+    * 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
+    * 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
+    */
+    configureConditionalRendering(condition: () => boolean, dependencies?: Array<DOMNodeReference>): DOMNodeReference;
+    /**
+     * Sets up validation and requirement rules for the field with enhanced error handling and dynamic updates.
      *
-     * @param {(this: DOMNodeReference) => boolean} 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
-     * registered on each to toggle the visibility of the target element based on the `condition` and the visibility of
-     * the target node.
-     * @returns - Instance of this
+     * @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 for method chaining
+     * @throws {ValidationConfigError} If validation setup fails
      */
-    configureConditionalRendering(condition: () => boolean, dependencies: Array<DOMNodeReference>): DOMNodeReference;
+    configureValidationAndRequirements(isRequired: () => boolean, isValid: () => boolean, fieldDisplayName: string, dependencies: Array<DOMNodeReference>): DOMNodeReference;
     /**
-     * Sets up validation and requirement rules for the field. This function dynamically updates the field's required status and validates its input based on the specified conditions.
-     *
-     * @param {function(this: DOMNodeReference): boolean} isRequired - A function that determines whether the field should be required. Returns `true` if required, `false` otherwise.
-     * @param {function(this: DOMNodeReference): boolean} isValid - A function that checks if the field's input is valid. Returns `true` if valid, `false` otherwise.
-     * @param {string} fieldDisplayName - The name of the field, used in error messages if validation fails.
-     * @param {Array<DOMNodeReference>} [dependencies] Other fields that this field’s requirement depends on. When these fields change, the required status of this field is re-evaluated. Make sure any DOMNodeReference used in `isRequired` or `isValid` is included in this array.
-     * @returns - Instance of this
+     * Sets up tracking for dependent fields using both event listeners and mutation observers.
+     * @private
      */
-    configureValidationAndRequirements(isRequired: (instance: DOMNodeReference) => boolean, isValid: (instance: DOMNodeReference) => boolean, fieldDisplayName: string, dependencies: Array<DOMNodeReference>): DOMNodeReference;
+    private _setupDependencyTracking;
     /**
      * Sets the required level for the field by adding or removing the "required-field" class on the label.
      *

package/dist/bundle.js

@@ -202,6 +202,12 @@ var ConditionalRenderingError = class extends Error {
     );
   }
 };
+var ValidationConfigError = class extends Error {
+  constructor(node, message) {
+    super(`Validation configuration error for ${node.target}: ${message}`);
+    this.name = "ValidationConfigError";
+  }
+};
 
 // src/DOMNodeReference.ts
 var _init = Symbol("_init");
@@ -322,7 +328,7 @@ var DOMNodeReference = class _DOMNodeReference {
    * Sets up an event listener based on the specified event type, executing the specified
    * event handler
    * @param {string} eventType - The DOM event to watch for
-   * @param {(this: DOMNodeReference, e: Event) => void} eventHandler - The callback function that runs when the
+   * @param {(e: Event) => void} eventHandler - The callback function that runs when the
    * specified event occurs
    * @returns - Instance of this
    */
@@ -348,7 +354,7 @@ var DOMNodeReference = class _DOMNodeReference {
   }
   /**
    *
-   * @param {function(this: DOMNodeReference): boolean | boolean} shouldShow - Either a function that returns true or false,
+   * @param {function(instance: DOMNodeReference): boolean | boolean} shouldShow - Either a function that returns true or false,
    * or a natural boolean to determine the visibility of this
    * @returns - Instance of this
    */
@@ -529,81 +535,151 @@ var DOMNodeReference = class _DOMNodeReference {
     return this;
   }
   /**
-   * Configures conditional rendering for the target element based on a condition
-   * and the visibility of one or more trigger elements.
-   *
-   * @param {(this: DOMNodeReference) => boolean} 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
-   * registered on each to toggle the visibility of the target element based on the `condition` and the visibility of
-   * the target node.
-   * @returns - Instance of this
-   */
+  * 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
+  * 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
+  * 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
+  */
   configureConditionalRendering(condition, dependencies) {
     try {
-      this.toggleVisibility(condition());
-      if (!dependencies) {
+      if (typeof condition !== "function") {
+        throw new TypeError("Condition must be a function");
+      }
+      condition = condition.bind(this);
+      const initialState = condition();
+      this.toggleVisibility(initialState);
+      if (!dependencies?.length) {
         console.warn(
-          `powerpagestoolkit: No dependencies were found when configuring conditional rendering for ${this}. Be sure that if you are referencing other nodes in your rendering logic, that you include those nodes in the dependency array`
+          `powerpagestoolkit: No dependencies provided for conditional rendering of ${this}. Include referenced nodes in the dependency array if using them in rendering logic.`
         );
         return this;
       }
+      const observers = [];
       dependencies.forEach((node) => {
-        node.on("change", () => this.toggleVisibility(condition()));
+        if (!node || !(node instanceof _DOMNodeReference)) {
+          throw new TypeError("Each dependency must be a valid DOMNodeReference instance");
+        }
+        const handleChange = () => {
+          try {
+            this.toggleVisibility(condition());
+          } catch (error) {
+            console.error("Error in change handler:", error);
+          }
+        };
+        node.on("change", handleChange);
         const observer = new MutationObserver(() => {
-          const display = window.getComputedStyle(
-            node.visibilityController
-          ).display;
-          this.toggleVisibility(display !== "none" && condition());
+          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"]
         });
+        observers.push(observer);
       });
       return this;
-    } catch (e) {
-      throw new ConditionalRenderingError(this, e);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new ConditionalRenderingError(this, errorMessage);
     }
   }
   /**
-   * Sets up validation and requirement rules for the field. This function dynamically updates the field's required status and validates its input based on the specified conditions.
+   * Sets up validation and requirement rules for the field with enhanced error handling and dynamic updates.
    *
-   * @param {function(this: DOMNodeReference): boolean} isRequired - A function that determines whether the field should be required. Returns `true` if required, `false` otherwise.
-   * @param {function(this: DOMNodeReference): boolean} isValid - A function that checks if the field's input is valid. Returns `true` if valid, `false` otherwise.
-   * @param {string} fieldDisplayName - The name of the field, used in error messages if validation fails.
-   * @param {Array<DOMNodeReference>} [dependencies] Other fields that this field’s requirement depends on. When these fields change, the required status of this field is re-evaluated. Make sure any DOMNodeReference used in `isRequired` or `isValid` is included in this array.
-   * @returns - Instance of this
+   * @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 for method chaining
+   * @throws {ValidationConfigError} If validation setup fails
    */
   configureValidationAndRequirements(isRequired, isValid, fieldDisplayName, dependencies) {
-    if (typeof Page_Validators !== "undefined") {
+    if (!fieldDisplayName?.trim()) {
+      throw new ValidationConfigError(this, "Field display name is required");
+    }
+    if (!Array.isArray(dependencies)) {
+      throw new ValidationConfigError(this, "Dependencies must be an array");
+    }
+    try {
+      isRequired = isRequired.bind(this);
+      isValid = isValid.bind(this);
+      if (typeof Page_Validators === "undefined") {
+        throw new ValidationConfigError(this, "Page_Validators not found");
+      }
+      const validatorId = `${this.element.id}Validator`;
       const newValidator = document.createElement("span");
       newValidator.style.display = "none";
-      newValidator.id = `${this.element.id}Validator`;
-      newValidator.controltovalidate = this.element.id;
-      newValidator.errormessage = `<a href='#${this.element.id}_label'>${fieldDisplayName} is a required field</a>`;
-      newValidator.evaluationfunction = isValid.bind(this);
+      newValidator.id = validatorId;
+      const validatorConfig = {
+        controltovalidate: this.element.id,
+        errormessage: `<a href='#${this.element.id}_label'>${fieldDisplayName} is a required field</a>`,
+        evaluationfunction: () => {
+          const isFieldRequired = isRequired();
+          const isFieldVisible = window.getComputedStyle(this.visibilityController).display !== "none";
+          if (!isFieldRequired || !isFieldVisible) {
+            return true;
+          }
+          return isValid();
+        }
+      };
+      Object.assign(newValidator, validatorConfig);
       Page_Validators.push(newValidator);
-    } else {
-      throw new Error(
-        "Attempted to add to Validator where Page_Validators do not exist"
+      this.setRequiredLevel(isRequired());
+      this._setupDependencyTracking(isRequired, dependencies);
+    } catch (error) {
+      throw new ValidationConfigError(
+        this,
+        `Failed to configure validation: ${error}`
       );
     }
-    this.setRequiredLevel(isRequired(this));
-    if (!dependencies) {
+    return this;
+  }
+  /**
+   * Sets up tracking for dependent fields using both event listeners and mutation observers.
+   * @private
+   */
+  _setupDependencyTracking(isRequired, dependencies) {
+    if (dependencies.length === 0) {
       console.warn(
-        `powerpagestoolkit: No dependencies were found when configuring requirement and validation for ${this}. Be sure that if you are referencing other nodes in your requirement or validation logic, that you include those nodes in the dependency array`
+        `powerpagestoolkit: No dependencies specified for ${this.element.id}. Include all referenced nodes in the dependency array for proper validation.`
       );
-      return this;
+      return;
     }
     dependencies.forEach((dep) => {
-      dep.element.addEventListener(
-        "change",
-        () => this.setRequiredLevel(isRequired(this))
-      );
+      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));
+        }
+      });
+      observer.observe(dep.visibilityController, {
+        attributes: true,
+        attributeFilter: ["style"],
+        subtree: false
+      });
+      if (dep.yesRadio || dep.noRadio) {
+        [dep.yesRadio, dep.noRadio].forEach((radio) => {
+          radio?.on("change", () => this.setRequiredLevel(isRequired(this)));
+        });
+      }
     });
-    return this;
   }
   /**
    * Sets the required level for the field by adding or removing the "required-field" class on the label.

package/dist/errors.d.ts

@@ -8,3 +8,6 @@ export declare class DOMNodeNotFoundError extends Error {
 export declare class ConditionalRenderingError extends Error {
     constructor(instance: DOMNodeReference, error: string);
 }
+export declare class ValidationConfigError extends Error {
+    constructor(node: DOMNodeReference, message: string);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "powerpagestoolkit",
-  "version": "2.5.0",
+  "version": "2.5.2",
   "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",
@@ -26,7 +26,7 @@
     "typescript-eslint": "^8.12.2"
   },
   "author": "KeatonBrewster",
-  "license": "SSPL-1.0",
+  "license": "AGPL-3.0-only",
   "type": "module",
   "repository": {
     "type": "git",