powerpagestoolkit 1.2.202 → 1.3.2

package/index.d.ts

@@ -1,182 +1,273 @@
-declare module "powerpagestoolkit" {
-  /**
-   * Class representing a reference to a DOM node.
-   */
-  class DOMNodeReference {
-    /**
-     * Creates an instance of DOMNodeReference.
-     * @param {string} querySelector - The CSS selector to find the desired DOM element.
-     */
-    constructor(querySelector: string);
-
-    element: HTMLElement | null;
-    isLoaded: boolean;
-
-    /**
-     * Initializes the DOMNodeReference instance by waiting for the element to be available in the DOM.
-     * @returns {Promise<DOMNodeReference>} A promise that resolves to a Proxy of the DOMNodeReference instance.
-     * @throws {Error} Throws an error if the element cannot be found using the provided query selector.
-     */
-    private init(): Promise<this>;
-
-    /**
-     * Hides the element by setting its display style to "none".
-     */
-    hide(): void;
-
-    /**
-     * Shows the element by restoring its default display style.
-     */
-    show(): void;
-
-    /**
-     * Hides the parent element by setting its display style to "none".
-     */
-    hideParent(): void;
-
-    /**
-     * Shows the parent element by restoring its default display style.
-     */
-    showParent(): void;
-
-    /**
-     * Hides the container (grandparent of the element) by setting its display style to "none".
-     */
-    hideContainer(): void;
-
-    /**
-     * Shows the container (grandparent of the element) by restoring its default display style.
-     */
-    showContainer(): void;
-
-    /**
-     * Sets the value of the HTML element.
-     * @param {string} value - The value to set for the HTML element.
-     */
-    setValue(value: string): void;
-
-    /**
-     * Gets the value of the HTML element.
-     * @returns {string} The current value of the HTML element.
-     */
-    getValue(): string;
-
-    /**
-     * Appends child elements to the HTML element.
-     * @param {...HTMLElement} elements - The elements to append to the HTML element.
-     */
-    append(...elements: HTMLElement[]): void;
-
-    /**
-     * Inserts elements after the HTML element.
-     * @param {...HTMLElement} elements - The elements to insert after the HTML element.
-     */
-    after(...elements: HTMLElement[]): void;
-
-    /**
-     * Retrieves the label associated with the HTML element.
-     * @returns {HTMLElement} The label element associated with this element.
-     * @throws {Error} Throws an error if the label cannot be found.
-     */
-    getLabel(): HTMLElement;
-
-    /**
-     * Appends child elements to the label associated with the HTML element.
-     * @param {...HTMLElement} elements - The elements to append to the label.
-     */
-    appendToLabel(...elements: HTMLElement[]): void;
-
-    /**
-     * Adds a click event listener to the HTML element.
-     * @param {Function} eventHandler - The function to execute when the element is clicked.
-     */
-    addClickListener(eventHandler: () => void): void;
-
-    /**
-     * Adds a change event listener to the HTML element.
-     * @param {Function} eventHandler - The function to execute when the element's value changes.
-     */
-    addChangeListener(eventHandler: () => void): void;
-
-    /**
-     * Unchecks both the yes and no radio buttons if they exist.
-     */
-    uncheckRadios(): void;
-
-    /**
-     * 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.
-     */
-    createValidation(
-      evaluationFunction: (value: any) => boolean,
-      fieldDisplayName: string
-    ): void;
-
-    /**
-     * Adds a tooltip with specified text to the label associated with the HTML element.
-     * @param {string} text - The text to display in the tooltip.
-     */
-    addLabelTooltip(text: string): void;
-
-    /**
-     * Sets the inner HTML content of the HTML element.
-     * @param {string} text - The text to set as the inner HTML of the element.
-     */
-    setTextContent(text: string): void;
-
-    /**
-     * Executes a callback function once the element is fully loaded.
-     * If the element is already loaded, the callback is called immediately.
-     * Otherwise, a MutationObserver is used to detect when the element is added to the DOM.
-     * @param {Function} callback - A callback function to execute once the element is loaded.
-     */
-    onceLoaded(callback: (instance: this) => void): void;
-  }
-
-  /**
-   * Creates and initializes a DOMNodeReference instance.
-   * @async
-   * @function createDOMNodeReference
-   * @param {string} querySelector - The CSS selector for the desired DOM element.
-   * @returns {Promise<DOMNodeReference>} A promise that resolves to a Proxy of the initialized DOMNodeReference instance.
-   */
-  export async function createDOMNodeReference(
-    querySelector: string
-  ): Promise<DOMNodeReference>;
-
-  interface Schema {
-    logicalName(): string;
-    value(): any; // Adjust this type based on the structure of your schema values
-  }
-
-  export const API: {
-    /**
-     * Creates a new record in DataVerse.
-     * @param schema An instance of a schema class, containing the desired information for the POST request.
-     * @returns A Promise resolving the successful results (record ID) of the POST request, or rejecting with the error.
-     */
-    createRecord(schema: Schema): Promise<string>;
-
-    /**
-     * Retrieves a single record from DataVerse.
-     * @param tableSetName The DataVerse SET name of the table being queried.
-     * @param recordID The GUID of the record to be retrieved.
-     * @param selectColumns *OPTIONAL* Custom OData query for advanced GET results. Format: select=column1,column2,column3...
-     * @returns A Promise resolving the successful results of the GET request, or rejecting with the error.
-     */
-    getRecord(
-      tableSetName: string,
-      recordID: string,
-      selectColumns?: string
-    ): Promise<any>; // Adjust return type as necessary
-
-    /**
-     * Retrieves multiple records from DataVerse.
-     * @param tableSetName The DataVerse SET name of the table being queried.
-     * @param queryParameters *OPTIONAL* OData query parameters for refining search results: format = $filter=filters&$select=columns
-     * @returns A Promise resolving the successful results of the GET request, or rejecting with the error.
-     */
-    getMultiple(tableSetName: string, queryParameters?: string): Promise<any>; // Adjust return type as necessary
-  };
+/**
+ * Class representing a reference to a DOM node.
+ */
+class DOMNodeReference {
+  /**
+   * Creates an instance of DOMNodeReference.
+   * @param {string} querySelector - The CSS selector to find the desired DOM element.
+   */
+  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.
+   * @returns {Promise<DOMNodeReference>} A promise that resolves to a Proxy of the DOMNodeReference instance.
+   * @throws {Error} Throws an error if the element cannot be found using the provided query selector.
+   */
+  private init(): Promise<this>;
+
+  /**
+   * Hides the element by setting its display style to "none".
+   */
+  hide(): void;
+
+  /**
+   * Shows the element by restoring its default display style.
+   */
+  show(): void;
+
+  /**
+   * Sets the value of 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
+   */
+  setValue(value: string): void;
+
+  /**
+   * Disables the element so that users cannot input any data
+   */
+  disable(): void;
+
+  /**
+   * Enables the element so that users can input data
+   */
+  enable(): void;
+
+  /**
+   * Prepends elements to the target
+   * @param {...HTMLElement} elements - The elements to prepend to the HTML element
+   */
+  prepend(...elements: HTMLElement[]): void;
+
+  /**
+   * Appends child elements to the HTML element.
+   * @param {...HTMLElement} elements - The elements to append to the HTML element.
+   */
+  append(...elements: HTMLElement[]): void;
+
+  /**
+   * Inserts elements before the HTML element.
+   * @param {...HTMLElement} elements - The elements to insert before the HTML element.
+   */
+  before(...elements: HTMLElement[]): void;
+
+  /**
+   * Inserts elements after the HTML element.
+   * @param {...HTMLElement} elements - The elements to insert after the HTML element.
+   */
+  after(...elements: HTMLElement[]): void;
+
+  /**
+   * Retrieves the label associated with the HTML element.
+   * @returns {HTMLElement} The label element associated with this element.
+   * @throws {Error} Throws an error if the label cannot be found.
+   */
+  getLabel(): HTMLElement;
+
+  /**
+   * Appends child elements to the label associated with the HTML element.
+   * @param {...HTMLElement} elements - The elements to append to the label.
+   */
+  appendToLabel(...elements: HTMLElement[]): void;
+
+  /**
+   * 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
+   */
+  on(eventType: string, eventHandler: (event: Event) => void): void;
+  /**
+   * Unchecks both the yes and no radio buttons if they exist.
+   */
+  uncheckRadios(): void;
+
+  /**
+   * 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.
+   */
+  configureValidationAndRequirements(
+    isRequired: (this: this) => boolean,
+    isValid: (this: this) => boolean,
+    fieldDisplayName: string,
+    dependencies: Array<DOMNodeReference>
+  ): void;
+
+  /**
+   * 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.
+   */
+  setRequiredLevel(isRequired: boolean): void;
+
+  /**
+   * Adds a tooltip with specified text to the label associated with the HTML element.
+   * @param {string} text - The text to display in the tooltip.
+   */
+  addLabelTooltip(text: string): void;
+
+  /**
+   * Adds a tooltip with the specified text to the element
+   * @param {string} text - The text to display in the tooltip
+   */
+  addTooltip(text: string): void;
+
+  /**
+   * Sets the inner HTML content of the HTML element.
+   * @param {string} text - The text to set as the inner HTML of the element.
+   */
+  setTextContent(text: string): void;
+
+  /**
+   *
+   * @param {boolean} shouldShow shows or hides the target
+   * if = true => show, if = false => hide
+   */
+  toggleVisibility(shouldShow: boolean): void;
+
+  /**
+   * 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 {DOMNodeReference[]} triggerNodes - 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.
+   */
+  configureConditionalRendering(
+    condition: (this: DOMNodeReference) => boolean,
+    triggerNodes: DOMNodeReference[]
+  ): void;
+
+  /**
+   * Executes a callback function once the element is fully loaded.
+   * If the element is already loaded, the callback is called immediately.
+   * Otherwise, a MutationObserver is used to detect when the element is added to the DOM.
+   * @param {Function} callback - A callback function to execute once the element is loaded.
+   */
+  onceLoaded(callback: (instance: this) => void): void;
+}
+
+/**
+ * Creates and initializes a DOMNodeReference instance.
+ * @async
+ * @function createDOMNodeReference
+ * @param {string} target - The CSS selector for the desired DOM element.
+ * @returns {Promise<DOMNodeReference>} A promise that resolves to a Proxy of the initialized DOMNodeReference instance.
+ */
+export declare async function createDOMNodeReference(
+  querySelector: string | HTMLElement
+): Promise<DOMNodeReference>;
+
+/**
+ * Interface representing an array of DOMNodeReference instances with additional methods.
+ */
+export interface DOMNodeReferenceArray extends Array<DOMNodeReference> {
+  /**
+   * Hides all the containers of the DOMNodeReference instances in the array.
+   */
+  hideAll(): void;
+
+  /**
+   * Shows all the containers of the DOMNodeReference instances in the array.
+   */
+  showAll(): void;
 }
+
+/**
+ * Creates and initializes multiple DOMNodeReference instances.
+ * @function createMultipleDOMNodeReferences
+ * @param {string} querySelector - The CSS selector for the desired DOM elements.
+ * @returns {Promise<DOMNodeReferenceArray>}
+ * A promise that resolves to an array of Proxies of initialized
+ * DOMNodeReference instances.
+ */
+export declare async function createMultipleDOMNodeReferences(
+  querySelector: string
+): Promise<DOMNodeReferenceArray>;
+
+interface Schema {
+  logicalName(): string;
+  value(): any; // Adjust this type based on the structure of your schema values
+}
+
+export declare const API: {
+  /**
+   * Creates a new record in DataVerse.
+   * @param schema An instance of a schema class, containing the desired information for the POST request.
+   * @returns A Promise resolving the successful results (record ID) of the POST request, or rejecting with the error.
+   */
+  createRecord(schema: Schema): Promise<string>;
+
+  /**
+   * Retrieves a single record from DataVerse.
+   * @param tableSetName The DataVerse SET name of the table being queried.
+   * @param recordID The GUID of the record to be retrieved.
+   * @param selectColumns *OPTIONAL* Custom OData query for advanced GET results. Format: select=column1,column2,column3...
+   * @returns A Promise resolving the successful results of the GET request, or rejecting with the error.
+   */
+  getRecord(
+    tableSetName: string,
+    recordID: string,
+    selectColumns?: string
+  ): Promise<any>; // Adjust return type as necessary
+
+  /**
+   * Retrieves multiple records from DataVerse.
+   * @param tableSetName The DataVerse SET name of the table being queried.
+   * @param queryParameters *OPTIONAL* OData query parameters for refining search results: format = $filter=filters&$select=columns
+   * @returns A Promise resolving the successful results of the GET request, or rejecting with the error.
+   */
+  getMultiple(tableSetName: string, queryParameters?: string): Promise<any>; // Adjust return type as necessary
+};

package/package.json

@@ -1,40 +1,61 @@
-{
-  "name": "powerpagestoolkit",
-  "version": "1.2.202",
-  "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"
-  },
-  "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",
-    "rimraf": "^6.0.1",
-    "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"
-  ],
-  "exports": {
-    ".": "./dist/index.bundle.js"
-  }
-}
+{
+  "name": "powerpagestoolkit",
+  "version": "1.3.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/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"
+  ]
+}