powerpagestoolkit 1.3.0 → 1.3.4

package/index.d.ts

@@ -8,12 +8,35 @@ class DOMNodeReference {
    */
   constructor(target: string): DOMNodeReference;
 
-  target: string;
+  /**
+   * The element targeted when instantiating DOMNodeReference.
+   * Made available in order to perform normal DOM traversal,
+   * or access properties not available through this class.
+   * @type {HTMLElement | null}
+   */
   element: HTMLElement | null;
   isLoaded: boolean;
-  visibilityController: HTMLElement | null;
-  defaultDisplay: string;
+  /**
+   * The value of the element that this node represents
+   * stays in syncs with the live DOM elements via event handler
+   * @type {string | null}
+   */
   value: string | null;
+  /**
+   * 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.
+   * @type {DOMNodeReference | undefined}
+   */
+  yesRadio?: DOMNodeReference;
+
+  /**
+   * 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.
+   * @type {DOMNodeReference | undefined}
+   */
+  noRadio?: DOMNodeReference;
 
   /**
    * Initializes the DOMNodeReference instance by waiting for the element to be available in the DOM.
@@ -24,104 +47,179 @@ class DOMNodeReference {
 
   /**
    * Hides the element by setting its display style to "none".
+   * @returns {DOMNodeReference} Returns 'this'
    */
-  hide(): void;
+  hide(): DOMNodeReference;
 
   /**
    * Shows the element by restoring its default display style.
+   * @returns {DOMNodeReference} Returns 'this'
    */
-  show(): void;
+  show(): DOMNodeReference;
 
   /**
    * Sets the value of the HTML element.
-   * @param {string} value - The value to set for the HTML element.
+   * @param {() => any} value - The value to set for the HTML element.
+   * for parents of boolean radios, pass true or false as value, or
+   * an expression returning a boolean
+   * @returns {DOMNodeReference} Returns 'this'
+   */
+  setValue(value: string): DOMNodeReference;
+
+  /**
+   * Disables the element so that users cannot input any data
+   * @returns {DOMNodeReference} Returns 'this'
+   */
+  disable(): DOMNodeReference;
+
+  /**
+   * Enables the element so that users can input data
+   * @returns {DOMNodeReference} Returns 'this'
+   */
+  enable(): DOMNodeReference;
+
+  /**
+   * Prepends elements to the target
+   * @param {HTMLElement[] | DOMNodeReference[]} nodes - The elements to prepend to the HTML element
+   * @returns {DOMNodeReference} Returns 'this'
    */
-  setValue(value: string): void;
+  prepend(...nodes: HTMLElement[] | DOMNodeReference[]): DOMNodeReference;
 
   /**
    * Appends child elements to the HTML element.
-   * @param {...HTMLElement} elements - The elements to append to the HTML element.
+   * @param {HTMLElement[] | DOMNodeReference[]} nodes - The elements to append to the HTML element.
+   * @returns {DOMNodeReference} Returns 'this'
    */
-  append(...elements: HTMLElement[]): void;
+  append(...nodes: HTMLElement[] | DOMNodeReference[]): DOMNodeReference;
+
+  /**
+   * Inserts elements before the HTML element.
+   * @param {HTMLElement[] | DOMNodeReference[]} nodes - The elements to insert before the HTML element.
+   * @returns {DOMNodeReference} Returns 'this'
+   */
+  before(...nodes: HTMLElement[] | DOMNodeReference[]): DOMNodeReference;
 
   /**
    * Inserts elements after the HTML element.
-   * @param {...HTMLElement} elements - The elements to insert after the HTML element.
+   * @param {HTMLElement[] | DOMNodeReference[]} nodes - The elements to insert after the HTML element.
+   * @returns {DOMNodeReference} Returns 'this'
    */
-  after(...elements: HTMLElement[]): void;
+  after(...nodes: HTMLElement[] | DOMNodeReference[]): DOMNodeReference;
 
   /**
    * Retrieves the label associated with the HTML element.
-   * @returns {HTMLElement} The label element associated with this element, or **null** if no label element is present
+   * @returns {HTMLElement} The label element associated with this element.
+   * @throws {Error} Throws an error if the label cannot be found.
    */
-  getLabel(): HTMLElement | null;
+  getLabel(): HTMLElement;
 
   /**
    * Appends child elements to the label associated with the HTML element.
    * @param {...HTMLElement} elements - The elements to append to the label.
+   * @returns {DOMNodeReference} Returns 'this'
    */
-  appendToLabel(...elements: HTMLElement[]): void;
+  appendToLabel(...elements: HTMLElement[]): DOMNodeReference;
 
   /**
-   * Adds a click event listener to the HTML element.
-   * @param {Function} eventHandler - The function to execute when the element is clicked.
+   * 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
+   * specified event occurs
+   * @returns {DOMNodeReference} Returns 'this'
    */
-  addClickListener(eventHandler: () => void): void;
+  on(eventType: string, eventHandler: (event: Event) => void): DOMNodeReference;
 
   /**
-   * Adds a change event listener to the HTML element.
-   * @param {Function} eventHandler - The function to execute when the element's value changes.
+   * Unchecks both the yes and no radio buttons if they exist.
+   * @returns {DOMNodeReference} Returns 'this'
    */
-  addChangeListener(eventHandler: () => void): void;
+  uncheckRadios(): DOMNodeReference;
 
   /**
-   * Unchecks both the yes and no radio buttons if they exist.
+   * 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 {DOMNodeReference} Returns 'this'
    */
-  uncheckRadios(): void;
+  configureValidationAndRequirements(
+    isRequired: (this: this) => boolean,
+    isValid: (this: this) => boolean,
+    fieldDisplayName: string,
+    dependencies: Array<DOMNodeReference>
+  ): DOMNodeReference;
 
   /**
-   * Creates a validation instance for the field.
-   * @param {Function} evaluationFunction - The function used to evaluate the field.
-   * @param {string} fieldDisplayName - The field name to display in error if validation
-   * fails.
+   * Sets the required level for the field by adding or removing the "required-field" class on the label.
+   *
+   * @param {boolean} 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 {DOMNodeReference} Returns 'this'
    */
-  createValidation(
-    evaluationFunction: (value: any) => boolean,
-    fieldDisplayName: string
-  ): void;
+  setRequiredLevel(isRequired: boolean): DOMNodeReference;
 
   /**
    * Adds a tooltip with specified text to the label associated with the HTML element.
    * @param {string} text - The text to display in the tooltip.
+   * @returns {DOMNodeReference} Returns 'this'
    */
-  addLabelTooltip(text: string): void;
+  addLabelTooltip(text: string): DOMNodeReference;
+
+  /**
+   * Adds a tooltip with the specified text to the element
+   * @param {string} text - The text to display in the tooltip
+   * @returns {DOMNodeReference} Returns 'this'
+   */
+  addTooltip(text: string): DOMNodeReference;
 
   /**
    * Sets the inner HTML content of the HTML element.
    * @param {string} text - The text to set as the inner HTML of the element.
+   * @returns {DOMNodeReference} Returns 'this'
+   */
+  setInnerHTML(text: string): DOMNodeReference;
+
+  /**
+   * Removes the element from the DOM
+   * @returns {DOMNodeReference} Returns 'this'
+   */
+  remove(): DOMNodeReference;
+
+  /**
+   *
+   * @param {Partial<CSSStyleDeclaration>} options - An object with the style properties (keys) and updated styles (values)
+   * to apply to the this. {"key": "value"}
+   * @returns {DOMNodeReference} Returns 'this'
    */
-  setTextContent(text: string): void;
+  setStyle(options: Partial<CSSStyleDeclaration>): DOMNodeReference;
 
   /**
    *
    * @param {boolean} shouldShow shows or hides the target
    * if = true => show, if = false => hide
+   * @returns {DOMNodeReference} Returns 'this'
    */
-  toggleVisibility(shouldShow: boolean): void;
+  toggleVisibility(shouldShow: boolean): DOMNodeReference;
 
   /**
+   * Configures conditional rendering for the target element based on a condition
+   * and the visibility of one or more trigger elements.
    *
-   * @param {Function} condition A Function that return a boolean value to set the
-   *  visibility of the targeted element. if condition() returns true, element is shown.
-   *  If false, element is hidden
-   * @param {DOMNodeReference} triggerNode The DOMNodeReference to which an
-   * event listener will be registered to change the visibility state of the calling
-   * DOMNodeReference
+   * @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 {DOMNodeReference} Returns 'this'
    */
   configureConditionalRendering(
-    condition: () => boolean,
-    triggerNode: DOMNodeReference
-  ): void;
+    condition: (this: DOMNodeReference) => boolean,
+    dependencies: DOMNodeReference[]
+  ): DOMNodeReference;
 
   /**
    * Executes a callback function once the element is fully loaded.

package/package.json

@@ -1,38 +1,61 @@
-{
-  "name": "powerpagestoolkit",
-  "version": "1.3.0",
-  "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/index.bundle.js",
-  "types": "index.d.ts",
-  "scripts": {
-    "build": "webpack",
-    "lint": "eslint ./src/JS/*"
-  },
-  "devDependencies": {
-    "@babel/core": "^7.25.8",
-    "@babel/node": "^7.26.0",
-    "@babel/preset-env": "^7.25.8",
-    "@types/node": "^22.8.0",
-    "babel-loader": "^9.2.1",
-    "clean-webpack-plugin": "^4.0.0",
-    "css-loader": "^7.1.2",
-    "eslint": "^8.57.1",
-    "eslint-plugin-import": "^2.31.0",
-    "style-loader": "^4.0.0",
-    "terser-webpack-plugin": "^5.3.4",
-    "typescript": "^5.6.3",
-    "webpack": "^5.95.0",
-    "webpack-cli": "^5.1.4"
-  },
-  "author": "KeatonBrewster",
-  "license": "SSPL-1.0",
-  "type": "module",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Keaton-Brewster/PowerPagesToolKit"
-  },
-  "files": [
-    "dist",
-    "index.d.ts"
-  ]
-}
+{
+  "name": "powerpagestoolkit",
+  "version": "1.3.4",
+  "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/index.bundle.js",
+  "types": "index.d.ts",
+  "scripts": {
+    "build": "webpack",
+    "lint": "eslint ./src/JS/*"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.25.8",
+    "@babel/node": "^7.26.0",
+    "@babel/preset-env": "^7.25.8",
+    "@types/node": "^22.8.0",
+    "babel-loader": "^9.2.1",
+    "clean-webpack-plugin": "^4.0.0",
+    "css-loader": "^7.1.2",
+    "eslint": "^8.57.1",
+    "eslint-plugin-import": "^2.31.0",
+    "style-loader": "^4.0.0",
+    "terser-webpack-plugin": "^5.3.4",
+    "typescript": "^5.6.3",
+    "webpack": "^5.95.0",
+    "webpack-cli": "^5.1.4"
+  },
+  "author": "KeatonBrewster",
+  "license": "SSPL-1.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Keaton-Brewster/PowerPagesToolKit"
+  },
+  "keywords": [
+    "powerpages",
+    "power pages",
+    "power platform",
+    "dynamics 365",
+    "power apps portal",
+    "dynamics 365 portal",
+    "portal",
+    "portal management",
+    "api",
+    "javascript",
+    "ajax",
+    "dataverse",
+    "dom-manipulation",
+    "node",
+    "http-request",
+    "json",
+    "rest-api",
+    "ajax-wrapper",
+    "form-management",
+    "frontend",
+    "web-development"
+  ],
+  "files": [
+    "dist",
+    "index.d.ts"
+  ]
+}