powerpagestoolkit 2.5.405 → 2.5.411

package/README.md

@@ -19,27 +19,39 @@ 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
-import {
-  createDOMNodeReference,
-  createMultipleDOMNodeReferences,
-} from "powerpagestoolkit";
+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)
 
-// Both methods support standard querySelector syntax:
+```typescript
+import { createRef } from "powerpagestoolkit";
+```
 
+Instantiate one, or multiple instances of a DOMNodeReference
+
+```typescript
 // Create a single reference
-const node = await createDOMNodeReference("#myElement");
+const node = await createRef("#myElement", false);
 
 // Create multiple references
-const nodes = await createMultipleDOMNodeReferences(".my-class");
+const nodes = await createRef(".my-class", true);
 ```
 
 #### Properties
@@ -60,14 +72,16 @@ const nodes = await createMultipleDOMNodeReferences(".my-class");
 
 ```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
@@ -76,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
@@ -154,7 +213,7 @@ node.addTooltip(
 );
 ```
 
-### DataVerse API
+- ### DataVerse API
 
 Type-safe wrapper for DataVerse API operations.
 
@@ -204,7 +263,7 @@ await API.updateRecord("contacts", "record-guid", {
 1. Always await DOMNodeReference creation:
 
 ```typescript
-const node = await createDOMNodeReference("#element");
+const node = await createRef("#element");
 ```
 
 2. Include all referenced nodes in dependency arrays:

package/dist/DOMNodeReference.d.ts

@@ -6,35 +6,31 @@ 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: HTMLElement;
+    element: Element;
     private visibilityController;
     checked: boolean;
     /**
      * 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>;
@@ -44,6 +40,7 @@ export default class DOMNodeReference {
      * @private
      */
     private _initValueSync;
+    private _initDateSync;
     /**
      * Updates the value and checked state based on element type
      * @public
@@ -54,12 +51,12 @@ export default class DOMNodeReference {
      * @private
      * @returns {ElementValue} Object containing value and optional checked state
      */
-    private getElementValue;
+    private _getElementValue;
     /**
      * Updates related radio buttons if this is part of a radio group
      * @private
      */
-    private updateRadioGroup;
+    private _updateRadioGroup;
     private _attachVisibilityController;
     private _attachRadioButtons;
     /**
@@ -205,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

@@ -103,10 +103,10 @@ var API = {
 var API_default = API;
 
 // src/waitFor.ts
-function waitFor(target) {
+function waitFor(target, root = document) {
   return new Promise((resolve, reject) => {
     const observer = new MutationObserver(() => {
-      const observedElement = document.querySelector(target);
+      const observedElement = root.querySelector(target);
       if (observedElement) {
         clearTimeout(timeout);
         observer.disconnect();
@@ -121,7 +121,7 @@ function waitFor(target) {
       clearTimeout(timeout);
       return resolve(target);
     }
-    const element = document.querySelector(target);
+    const element = root.querySelector(target);
     if (element) {
       clearTimeout(timeout);
       return resolve(element);
@@ -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.
    */
   /******/
   /******/
@@ -251,6 +250,7 @@ var DOMNodeReference = class _DOMNodeReference {
     this.isLoaded = false;
     this.defaultDisplay = "";
     this.value = null;
+    this.updateValue = this.updateValue.bind(this);
   }
   async [_init]() {
     try {
@@ -275,38 +275,64 @@ var DOMNodeReference = class _DOMNodeReference {
    * based on element type.
    * @private
    */
-  _initValueSync() {
-    this.updateValue();
-    const input = this.element;
-    const eventMapping = {
-      checkbox: "click",
-      radio: "click",
-      "select-one": "change",
-      select: "change",
-      "select-multiple": "change"
-    };
-    const boundUpdateValue = this.updateValue.bind(this);
-    const eventType = eventMapping[input.type] || "input";
-    this.element.addEventListener(eventType, boundUpdateValue);
+  async _initValueSync() {
+    try {
+      this.updateValue();
+      if (!(this.element instanceof HTMLElement)) {
+        throw new Error("Element is not a valid HTML element");
+      }
+      const eventMapping = {
+        checkbox: "click",
+        radio: "click",
+        select: "change",
+        "select-multiple": "change"
+        // Add other input types as needed
+      };
+      let eventType;
+      if (this.element instanceof HTMLSelectElement) {
+        eventType = "change";
+      } else if (this.element instanceof HTMLInputElement) {
+        eventType = eventMapping[this.element.type] || "input";
+      } else {
+        eventType = "input";
+      }
+      this.element.addEventListener(eventType, this.updateValue);
+      if (this.element instanceof HTMLInputElement && this.element.dataset.type === "date") {
+        await this._initDateSync(this.element);
+      }
+    } catch (error) {
+      throw new DOMNodeInitializationError(
+        this,
+        `Failed to initialize value sync: ${error}`
+      );
+    }
+  }
+  async _initDateSync(element) {
+    const parentElement = element.parentElement;
+    if (!parentElement) {
+      throw new Error("Date input must have a parent element");
+    }
+    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();
+    const elementValue = this._getElementValue();
     this.value = elementValue.value;
     if (elementValue.checked !== void 0) {
       this.checked = elementValue.checked;
     }
-    this.updateRadioGroup();
+    this._updateRadioGroup();
   }
   /**
    * Gets the current value of the element based on its type
    * @private
    * @returns {ElementValue} Object containing value and optional checked state
    */
-  getElementValue() {
+  _getElementValue() {
     const input = this.element;
     const select = this.element;
     switch (input.type) {
@@ -332,7 +358,7 @@ var DOMNodeReference = class _DOMNodeReference {
         };
       default:
         return {
-          value: this.element.classList.contains("decimal") ? parseFloat(input.value) : input.value
+          value: this.element.classList.contains("decimal") || this.element.classList.contains("money") ? parseFloat(input.value) : input.value
         };
     }
   }
@@ -340,7 +366,7 @@ var DOMNodeReference = class _DOMNodeReference {
    * Updates related radio buttons if this is part of a radio group
    * @private
    */
-  updateRadioGroup() {
+  _updateRadioGroup() {
     if (this.yesRadio instanceof _DOMNodeReference && this.noRadio instanceof _DOMNodeReference) {
       this.yesRadio.updateValue();
       this.noRadio?.updateValue();
@@ -507,7 +533,7 @@ var DOMNodeReference = class _DOMNodeReference {
         );
         if (childInputs.length > 0) {
           const clearPromises = childInputs.map(async (input) => {
-            const inputRef = await createDOMNodeReference(input);
+            const inputRef = await createDOMNodeReference(input, false);
             return inputRef.clearValues();
           });
           await Promise.all(clearPromises);
@@ -683,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);
@@ -765,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,
@@ -775,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);
         });
       }
     });
@@ -854,50 +888,59 @@ var DOMNodeReference = class _DOMNodeReference {
 };
 
 // src/createDOMNodeReferences.ts
-async function createDOMNodeReference(target) {
+async function createDOMNodeReference(target, multiple = false) {
   try {
+    const isMultiple = typeof multiple === "function" ? multiple() : multiple;
+    if (isMultiple) {
+      if (typeof target !== "string") {
+        throw new Error(
+          `'target' must be of type 'string' if 'multiple' is set to 'true'. Received type: '${typeof target}'`
+        );
+      }
+      const elements = Array.from(
+        document.querySelectorAll(target)
+      );
+      const initializedElements = await Promise.all(
+        elements.map(async (element) => {
+          const instance2 = new DOMNodeReference(element);
+          await instance2[_init]();
+          return new Proxy(instance2, createProxyHandler());
+        })
+      );
+      return enhanceArray(initializedElements);
+    }
     const instance = new DOMNodeReference(target);
     await instance[_init]();
-    return new Proxy(instance, {
-      get: (target2, prop) => {
-        if (prop.toString().startsWith("_")) return void 0;
-        const value = target2[prop];
-        if (typeof value === "function" && prop !== "onceLoaded") {
-          return (...args) => {
-            target2.onceLoaded(() => value.apply(target2, args));
-            return target2;
-          };
-        }
-        return value;
-      }
-    });
+    return new Proxy(instance, createProxyHandler());
   } catch (e) {
     throw new Error(e);
   }
 }
-async function createMultipleDOMNodeReferences(querySelector) {
-  try {
-    const elements = Array.from(
-      document.querySelectorAll(querySelector)
-    );
-    const initializedElements = await Promise.all(
-      elements.map((element) => createDOMNodeReference(element))
-    );
-    const domNodeArray = initializedElements;
-    domNodeArray.hideAll = () => domNodeArray.forEach((instance) => instance.hide());
-    domNodeArray.showAll = () => domNodeArray.forEach((instance) => instance.show());
-    return domNodeArray;
-  } catch (e) {
-    console.error(
-      `There was an error creating multiple DOMNodeReferences: ${e}`
-    );
-    throw new Error(e);
-  }
+function createProxyHandler() {
+  return {
+    get: (target, prop) => {
+      if (prop.toString().startsWith("_")) return void 0;
+      const value = target[prop];
+      if (typeof value === "function" && prop !== "onceLoaded") {
+        return (...args) => {
+          target.onceLoaded(() => value.apply(target, args));
+          return target;
+        };
+      }
+      return value;
+    }
+  };
+}
+function enhanceArray(array) {
+  const enhanced = array;
+  enhanced.hideAll = () => enhanced.forEach((instance) => instance.hide());
+  enhanced.showAll = () => enhanced.forEach((instance) => instance.show());
+  return enhanced;
 }
 export {
   API_default as API,
-  createDOMNodeReference,
-  createMultipleDOMNodeReferences
+  createDOMNodeReference as createRef,
+  waitFor
 };
 
 

package/dist/createDOMNodeReferences.d.ts

@@ -2,14 +2,8 @@ import DOMNodeReference from "./DOMNodeReference.js";
 /**
  * Creates and initializes a DOMNodeReference instance.
  * @async
- * @param {string | HTMLElement} target - The CSS selector for the desired DOM element, or, optionally, the element itself for which to create a DOMNodeReference.
- * @returns {Promise<DOMNodeReference>} A promise that resolves to a Proxy of the initialized DOMNodeReference instance.
+ * @param  target - The CSS selector for the desired DOM element, or, optionally, the element itself for which to create a DOMNodeReference.
+ * @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 declare function createDOMNodeReference(target: HTMLElement | string): Promise<DOMNodeReference>;
-/**
- * Creates and initializes multiple DOMNodeReference instances.
- * @async
- * @param {string} querySelector - The CSS selector for the desired DOM elements.
- * @returns {Promise<DOMNodeReference[]>} A promise that resolves to an array of Proxies of initialized DOMNodeReference instances.
- */
-export declare function createMultipleDOMNodeReferences(querySelector: string): Promise<DOMNodeReference[]>;
+export default function createDOMNodeReference(target: HTMLElement | string, multiple?: (() => boolean) | boolean): Promise<DOMNodeReference | DOMNodeReferenceArray>;

package/dist/index.d.ts

@@ -1,7 +1,5 @@
 import "./style.css";
 import API from "./API.js";
-import DOMNodeReference from "./DOMNodeReference.js";
-import { createDOMNodeReference, createMultipleDOMNodeReferences } from "./createDOMNodeReferences.js";
-interface DOMNodeRef extends DOMNodeReference {
-}
-export { API, createDOMNodeReference, createMultipleDOMNodeReferences, DOMNodeRef, };
+import createRef from "./createDOMNodeReferences.js";
+import waitFor from "./waitFor.js";
+export { API, createRef, waitFor };

package/dist/waitFor.d.ts

@@ -1 +1,7 @@
-export default function waitFor(target: HTMLElement | string): Promise<HTMLElement>;
+/**
+ *
+ * @param target basic querySelector syntax to select an element
+ * @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>;

package/package.json

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