powerpagestoolkit 2.7.0 → 2.7.2

package/README.md

@@ -35,7 +35,7 @@ createRef(
   options: {
     multiple: (() => boolean) | boolean = false,
     root: HTMLElement,
-    timeout: number
+    timeoutMs:number
   }
 ): Promise<DOMNodeReference | DOMNodeReference[]>;
 ```
@@ -66,7 +66,7 @@ createRef takes two main arguments:
         <pre><code class="language-javascript">{
   multiple: () => boolean | boolean,
   root: HTMLElement,
-  timeout: number
+  timeoutMs:number
 }</code></pre>
       </td>
       <td style="border: 1px solid #ddd; padding: 8px;">
@@ -85,10 +85,10 @@ import { createRef } from "powerpagestoolkit";
 Instantiate one, or multiple instances of a DOMNodeReference, and optionally configure advanced options
 
 ```javascript
-// Create a single reference
+// Create a single reference (i.e. 'querySelector')
 const node = await createRef("#myElement");
 
-// Create multiple references
+// Create multiple references (i.e. 'querySelectorAll')
 const nodes = await createRef(".my-class", { multiple: true });
 
 /******************/
@@ -98,7 +98,7 @@ const nodes = await createRef(".my-class", { multiple: true });
 
 // If the node you are targeting is not available at the initial execution
 // of the script, set a timeout for 2 seconds
-const node2 = await createRef("#target", { timeout: 2000 });
+const node2 = await createRef("#target", { timeoutMs:2000 });
 
 // need to target a node within a specific node? use that node as the root
 const otherElement = document.getElementById("id");
@@ -107,7 +107,7 @@ const node3 = await createRef("#target", { root: otherElement });
 // implement all options:
 const nodes2 = await createRef("#target", {
   multiple: true,
-  timeout: 4000,
+  timeoutMs:4000,
   root: otherElement,
 });
 ```
@@ -142,76 +142,116 @@ node.on("click", function (e) {
 ...
 ```
 
-##### Visibility Control
+##### Business Rule Application
 
-```typescript
-// Basic visibility
-node.hide();
-node.show();
-```
+This utility provides a flexible way to dynamically control field visibility, requirement status, values, and enabled states based on dependencies within PowerPages forms.
 
-**_Advanced conditional rendering_**
+_Method Signature:_
 
-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
+```typescript
+applyBusinessRule(
+  rule: BusinessRule,
+  dependencies: DOMNodeReference[]
+): DOMNodeReference; /* Instance of this is returned for optional
+ method chaining */
+```
 
-_Method signature:_
+**BusinessRule Definition**
 
 ```typescript
-configureConditionalRendering(
+interface BusinessRule {
+  setVisibility?: [
     condition: () => boolean,
-    dependencies?: DOMNodeReference[],
-    clearValuesOnHide: boolean = true
-  ): DOMNodeReference /* Instance of this returned
-  for optional method chaining */
+    clearValuesOnHide?: boolean = true
+    ];
+  setRequired?: [
+    isRequired: () => boolean,
+    isValid: () => boolean
+  ];
+  setValue?: [
+    condition: () => boolean,
+    value: () => any | any
+    ];
+  setDisabled?: () => boolean;
+}
 ```
 
-_Example implementation:_
+##### Visibility Control
 
 ```typescript
-node.configureConditionalRendering(
-  function () // Function to evaluate wether this node should be visible or not
+// Show the 'taxIdField' only when
+// 'businessTypeField' is set to 'Corporation' or 'LLC'
+taxIdField.applyBusinessRule(
   {
-    return otherNode.value === "some value";
+    setVisibility: [
+      () =>
+        businessTypeField.value === "Corporation" ||
+        businessTypeField.value === "LLC",
+    ],
   },
-  [otherNode] /* Dependency array | if the values or visibility of these
-  change, the function is re-evaluated */,
+  [businessTypeField] // Re-evaluate when businessTypeField changes
+);
 
-  true /* should the values in the targeted elements (this.element)
-  be cleared if this node is hidden? Default = true */
+// Optionally disable 'clearValuesOnHide':
+taxIdField.applyBusinessRule(
+  {
+    setVisibility: [
+      () =>
+        businessTypeField.value === "Corporation" ||
+        businessTypeField.value === "LLC",
+      false, // defaults to true. False will prevent the fields from losing it's value if it is hidden
+    ],
+  },
+  [businessTypeField] // Re-evaluate when businessTypeField changes
 );
 ```
 
 ##### Validation and Requirements
 
-This utility enhances PowerPages forms by adding dynamic field validation and conditional requirements based on other field values.
-
-_Method signature:_
-
 ```typescript
-configureValidationAndRequirements(
-  isRequired: () => boolean,
-  isValid: () => boolean,
-  fieldDisplayName: string,
-  dependencies: DOMNodeReference[]
-): DOMNodeReference; /* instance of this is returned for optional
- method chaining */
+// Require 'taxIdField' when 'businessTypeField' is 'Corporation' or 'LLC'
+taxIdField.applyBusinessRule(
+  {
+    setRequired: [
+      function () {
+        return (
+          businessTypeField.value === "Corporation" ||
+          businessTypeField.value === "LLC"
+        );
+      },
+      function () {
+        return this.value != null && this.value !== "";
+      },
+    ],
+  },
+  [businessTypeField] // Revalidate when businessTypeField changes
+);
 ```
 
-_Example implementation:_
+##### Setting Field Values Conditionally
 
 ```typescript
-node.configureValidationAndRequirements(
-  // 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 !== "";
+// Set default industry value when 'businessTypeField' is 'Corporation'
+industryField.applyBusinessRule(
+  {
+    setValue: [
+      () => businessTypeField.value === "Corporation",
+      "Corporate"
+    ],
   },
+  [businessTypeField] // Apply value when businessTypeField changes
+);
+```
 
-  "Contact Phone", // Shows in error message: "Contact Phone is required"
+##### Enabling and Disabling Fields
 
-  [dependentNode] // Revalidate when dependentNode changes
+```typescript
+// Disable 'taxIdField' when 'businessTypeField' is 'Individual'
+taxIdField.applyBusinessRule(
+  {
+    setDisabled: () => businessTypeField.value === "Individual",
+  },
+  [businessTypeField] // Enable/disable when businessTypeField changes
 );
 ```
 
@@ -261,7 +301,6 @@ _Enabling/Disabling inputs_
 ```typescript
 node.disable();
 node.enable();
-
 ```
 
 ##### Label and Tooltip Management
@@ -295,6 +334,89 @@ title.addTooltip("This is an Example of a tooltip!", { color: "red" });
 
 ![Example](./assets//infoIconExample.gif)
 
+Here's an improved markdown documentation with more comprehensive details:
+
+### BindForm Method
+
+The `bindForm` method simplifies form element management in DataVerse by providing a semantic and efficient way to access form controls, sections, and tabs.
+
+##### Key Features
+
+- Retrieves form definition directly from DataVerse
+- Automatically generates references for:
+  - Controls
+  - Sections
+  - Tabs
+
+##### Element Types
+
+| Element Type | Description                                 | Accessibility             |
+| ------------ | ------------------------------------------- | ------------------------- |
+| `control`    | Includes all form fields and sub-grids      | Accessed via logical name |
+| `section`    | Standard PowerApps form sections            | Accessed via logical name |
+| `tab`        | Form tabs corresponding to PowerApps layout | Accessed via logical name |
+
+##### Usage Example
+
+```javascript
+import { bindForm } from "powerpagestoolkit";
+
+// Basic form binding
+bindForm("form-guid").then((form) => {
+  // Access elements by their logical name
+  const nameField = form["name"];
+
+  // execute custom methods
+  nameField.applyBusinessRule(
+    {
+      setVisibility: [() => someNode.value === "desired value"],
+    },
+    [someNode]
+  );
+
+  // Or executes methods immediately upon accessing
+  form["phonenumber"].addTooltip("Example tooltip text");
+});
+```
+
+##### Method Signature
+
+```typescript
+/**
+ * Binds a form by its GUID and returns a collection of form elements
+ * @param formGuid Unique identifier for the form
+ * @returns Promise resolving to form element references
+ */
+function bindForm(formGuid: string): Promise<DOMNodeReferenceArray & Record<string: DOMNodeReference>>;
+```
+
+##### Benefits
+
+- Reduces code complexity
+- Improves readability
+- Provides type-safe access to form elements
+- Supports flexible form interactions
+
+##### Best Practices
+
+- Use logical names consistently
+- Handle async nature of form binding
+- Leverage TypeScript for enhanced type checking
+
+##### Error Handling
+
+Ensure proper error handling for form binding:
+
+```javascript
+bindForm("form-guid")
+  .then((form) => {
+    // Form processing
+  })
+  .catch((error) => {
+    console.error("Form binding failed", error);
+  });
+```
+
 ### DataVerse API
 
 Perform secure API calls to DataVerse from your PowerPages site. This method implements the shell deferred token to send requests with `__RequestVerificationToken`

package/dist/import_map.json

@@ -0,0 +1,6 @@
+{
+  "imports": {
+    "powerpagestoolkit/": "./",
+    "powerpagestoolkit": "./index.js"
+  }
+}

package/dist/src/constants/eventMapping.d.ts

@@ -0,0 +1,7 @@
+/// <reference path="../globals.d.ts" />
+/**
+ * For use in setting up event management in the instances of DOMNodeReference
+ * @see {@link DOMNodeReference}
+ */
+declare const eventMapping: Record<string, keyof HTMLElementEventMap>;
+export default eventMapping;

package/dist/src/constants/symbols.d.ts

@@ -0,0 +1,14 @@
+/// <reference path="../globals.d.ts" />
+export declare const init: unique symbol;
+export declare const destroy: unique symbol;
+export declare const valueSync: unique symbol;
+export declare const dateSync: unique symbol;
+export declare const getElementValue: unique symbol;
+export declare const attachVisibilityController: unique symbol;
+export declare const attachRadioButtons: unique symbol;
+export declare const bindMethods: unique symbol;
+export declare const debounceTime: unique symbol;
+export declare const observers: unique symbol;
+export declare const boundEventListeners: unique symbol;
+export declare const isValidFormElement: unique symbol;
+export declare const registerEventListener: unique symbol;

package/dist/{API.d.ts → src/core/API.d.ts}

@@ -1,10 +1,18 @@
-declare const API: {
+/// <reference path="../globals.d.ts" />
+/**
+ * Provides abstract class `API` that allows basic create, read, and update operations in DataVerse via the PowerPages API
+ * @method `createRecord` - Create a record in DataVerse
+ * @method `getRecord<T>` - Get a record by ID from DataVerse
+ * @method `getMultiple` - Get multiple records from DataVerse; with optional OData filtering
+ * @method `updateRecord` - Update a record by ID in DataVerse
+ */
+declare abstract class API {
     /**
      * @param tableSetName The dataverse set name for the table that you are updating a record in
      * @param data The JSON of the fields and data that are to be updated on the targeted record
      * @returns a Promise resolving the successful results *[record id]* of the POST request, or rejecting the failed results *[error]* of the POST request.
      */
-    createRecord(tableSetName: string, data: object): Promise<string>;
+    static createRecord(tableSetName: string, data: JSON): Promise<string>;
     /**
      *
      * @param tableSetName The DataVerse SET name of the table being queried
@@ -12,14 +20,14 @@ declare const API: {
      * @param selectColumns *OPTIONAL* if desired, enter your own 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 the failed results of the GET request
      */
-    getRecord<T>(tableSetName: string, recordID: string, selectColumns?: string): Promise<T>;
+    static getRecord<T>(tableSetName: string, recordID: string, selectColumns?: string): Promise<T>;
     /**
      *
      * @param tableSetName The dataverse set name of the table being queried
      * @param queryParameters *OPTIONAL* the 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 the failed results of the GET request
      */
-    getMultiple(tableSetName: string, queryParameters?: string): Promise<Array<object>>;
+    static getMultiple(tableSetName: string, queryParameters?: string): Promise<Array<object>>;
     /**
      *
      * @param tableSetName The dataverse set name for the table that you are updating a record in
@@ -27,6 +35,6 @@ declare const API: {
      * @param data The JSON of the fields and data that are to be updated on the targeted record
      * @returns A Promise with the results of the API execution
      */
-    updateRecord(tableSetName: string, recordId: string, data: object): Promise<any>;
-};
+    static updateRecord(tableSetName: string, recordId: string, data: object): Promise<any>;
+}
 export default API;

package/dist/{DOMNodeReference.d.ts → src/core/DOMNodeReference.d.ts}

@@ -1,54 +1,16 @@
-interface IBusinessRule {
-    /**
-     * @param 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 clearValuesOnHide Should the values in the targeted field be cleared when hidden? Defaults to true
-     */
-    setVisibility?: [condition: () => boolean, clearValuesOnHide?: boolean];
-    /**
-     * @param isRequired Function determining if field is required
-     * @param isValid Function validating field input. allows access to the invoked expression passed by {@link isRequired}
-     */
-    setRequired?: [
-        isRequired: () => boolean,
-        isValid: (isRequired: () => boolean) => boolean
-    ];
-    /**
-     * @param condition A function to determine if the value provided should be applied to this field
-     * @param 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?: [condition: () => boolean, value: any];
-    /**
-     * @param condition A function to determine if this field
-     * should be enabled in a form, or disabled. True || 1 = disabled. False || 0 = enabled
-     */
-    setDisabled?: [condition: () => boolean];
-}
-export declare const _init: unique symbol;
-declare const _destroy: unique symbol;
-declare const _valueSync: unique symbol;
-declare const _dateSync: unique symbol;
-declare const _getElementValue: unique symbol;
-declare const _updateRadioGroup: unique symbol;
-declare const _attachVisibilityController: unique symbol;
-declare const _attachRadioButtons: unique symbol;
-declare const _bindMethods: unique symbol;
-declare const _debounceTime: unique symbol;
-declare const _observers: unique symbol;
-declare const _boundEventListeners: unique symbol;
+/// <reference path="../globals.d.ts" />
+import * as s from "../constants/symbols.d.ts";
 export default class DOMNodeReference {
     target: Element | string;
     logicalName?: string;
     root: Element;
-    private [_debounceTime];
-    private isLoaded;
-    private defaultDisplay;
-    private [_observers];
-    private [_boundEventListeners];
+    protected [s.debounceTime]: number;
+    protected isLoaded: boolean;
+    protected defaultDisplay: string;
+    protected [s.observers]: Array<MutationObserver>;
+    protected [s.boundEventListeners]: Array<BoundEventListener>;
+    protected isRadio: boolean;
+    protected radioType: RadioType | null;
     /**
      * The value of the element that this node represents
      * stays in syncs with the live DOM elements?.,m  via event handler
@@ -60,7 +22,7 @@ export default class DOMNodeReference {
      * or access properties not available through this class.
      */
     element: HTMLElement;
-    private visibilityController;
+    protected visibilityController: HTMLElement;
     checked: boolean;
     /**
      * Represents the 'yes' option of a boolean radio field.
@@ -81,35 +43,33 @@ export default class DOMNodeReference {
      * Defaults to 'document.body'
      */
     /******/ /******/ constructor(target: Element | string, root: Element | undefined, debounceTime: number);
-    [_init](): Promise<void>;
-    private eventMapping;
+    private extractLogicalName;
+    [s.init](): Promise<void>;
     /**
      * Initializes value synchronization with appropriate event listeners
      * based on element type.
-     * @private
      */
-    private [_valueSync];
-    private [_dateSync];
+    protected [s.valueSync](): void;
+    private determineEventType;
+    private isDateInput;
+    protected [s.isValidFormElement](element: Element): element is FormElement;
+    protected [s.registerEventListener](element: Element, eventType: keyof HTMLElementEventMap, handler: (e: Event) => unknown): void;
+    protected [s.dateSync](element: HTMLInputElement): Promise<void>;
     /**
      * Gets the current value of the element based on its type
-     * @private
+     * @protected
      * @returns Object containing value and optional checked state
      */
-    private [_getElementValue];
-    /**
-     * Updates related radio buttons if this is part of a radio group
-     * @private
-     */
-    private [_updateRadioGroup];
-    private [_attachVisibilityController];
-    private [_attachRadioButtons];
-    private [_bindMethods];
-    private [_destroy];
+    protected [s.getElementValue](): ElementValue;
+    protected [s.attachVisibilityController](): void;
+    protected [s.attachRadioButtons](): Promise<void>;
+    protected [s.bindMethods](): void;
+    protected [s.destroy](): void;
     /**
      * Updates the value and checked state based on element type
      * @public
      */
-    updateValue(): void;
+    updateValue(e?: Event): void;
     /**
      * Sets up an event listener based on the specified event type, executing the specified
      * event handler
@@ -130,7 +90,6 @@ export default class DOMNodeReference {
      */
     show(): DOMNodeReference;
     /**
-     *
      * @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]
@@ -164,7 +123,6 @@ export default class DOMNodeReference {
      */
     enable(): DOMNodeReference;
     /**
-     *
      * @param elements - The elements to prepend to the element targeted by this.
      * @returns - Instance of this [provides option to method chain]
      */
@@ -218,7 +176,6 @@ export default class DOMNodeReference {
      */
     remove(): this;
     /**
-     *
      * @param options and object containing the styles you want to set : {key: value} e.g.: {'display': 'block'}
      * @returns - Instance of this [provides option to method chain]
      */
@@ -230,12 +187,12 @@ export default class DOMNodeReference {
     uncheckRadios(): DOMNodeReference;
     /**
      * Applies a business rule to manage visibility, required state, value, and disabled state dynamically.
-     *
+     * @see {@link BusinessRule}
      * @param rule The business rule containing conditions for various actions.
      * @param dependencies For re-evaluation conditions when the state of the dependencies change
      * @returns Instance of this for method chaining.
      */
-    applyBusinessRule(rule: IBusinessRule, dependencies: DOMNodeReference[]): DOMNodeReference;
+    applyBusinessRule(rule: BusinessRule, dependencies: DOMNodeReference[]): DOMNodeReference;
     /**
      * Configures conditional rendering for the target element based on a condition
      * and the visibility of one or more trigger elements.
@@ -263,13 +220,18 @@ export default class DOMNodeReference {
     configureValidationAndRequirements(isRequired: () => boolean, isValid: () => boolean, fieldDisplayName: string, dependencies: Array<DOMNodeReference>): DOMNodeReference;
     /**
      * Sets up tracking for dependencies using both event listeners and mutation observers.
-     * @private
+     * @protected
      * @param handler The function to execute when dependencies change
      * @param dependencies Array of dependent DOM nodes to track
      * @param options Additional configuration options. clearValuesOnHide defaults to false.
      * all other options defaults to true
      */
-    private _configDependencyTracking;
+    protected _configDependencyTracking(handler: () => void, dependencies: Array<DOMNodeReference>, options?: {
+        clearValuesOnHide?: boolean;
+        observeVisibility?: boolean;
+        trackInputEvents?: boolean;
+        trackRadioButtons?: boolean;
+    }): void;
     /**
      * Sets the required level for the field by adding or removing the "required-field" class on the label.
      *
@@ -287,4 +249,3 @@ export default class DOMNodeReference {
      */
     onceLoaded(callback: (instance: DOMNodeReference) => any): any;
 }
-export {};

package/dist/{DOMNodeReferenceArray.d.ts → src/core/DOMNodeReferenceArray.d.ts}

@@ -1,5 +1,6 @@
-import DOMNodeReference from "./DOMNodeReference.js";
-export declare class DOMNodeReferenceArray extends Array<DOMNodeReference> {
+/// <reference path="../globals.d.ts" />
+import type DOMNodeReference from "./DOMNodeReference.d.ts";
+export default class DOMNodeReferenceArray extends Array<DOMNodeReference> {
     /**
      * Hides all the containers of the DOMNodeReference instances in the array.
      */
@@ -9,4 +10,3 @@ export declare class DOMNodeReferenceArray extends Array<DOMNodeReference> {
      */
     showAll(this: DOMNodeReferenceArray): DOMNodeReferenceArray;
 }
-export declare function enhanceArray<T extends string>(array: DOMNodeReference[]): DOMNodeReferenceArray & Record<T, DOMNodeReference>;

package/dist/src/core/List.d.ts

@@ -0,0 +1,13 @@
+/// <reference path="../globals.d.ts" />
+export default class List {
+    private static _instance;
+    private _root;
+    private _listItems;
+    private _observer;
+    private constructor();
+    static get(): List;
+    private _observe;
+    private _update;
+    private _destroy;
+    destroy(): void;
+}

package/dist/src/core/bindForm.d.ts

@@ -0,0 +1,28 @@
+/// <reference path="../globals.d.ts" />
+import type DOMNodeReference from "./DOMNodeReference.d.ts";
+import type DOMNodeReferenceArray from "./DOMNodeReferenceArray.d.ts";
+/**
+ * When loading into a page in PowerPages that has a form,
+ * you can use this function by passing in the GUID of the form, and you will receive an array/record
+ * of {@link DOMNodeReference}s that represent all fields, sections, sub-grids, and tabs of the given form.
+ * Access these properties of the {@link BoundForm} using the logical name of the control you need to access: form['logical_name']
+ * you can then execute all the methods available from DOMNodeReference
+ * @param formId - The string GUID of the form you want to bind to
+ * @returns An array of DOMNodeReferences, accessible as properties of a Record<string, DOMNodeReference> i.e. formProp = form["some_logicalName"]
+ * @example
+ * ```js
+ * bindForm("form-guid-0000").then((form) => {
+ *    //...use the form
+ *    const field = form["field_logical_name"]
+ *    // or
+ *    form["other_logical_name"].someMethod()
+ * })
+ *
+ * // or
+ *
+ * const form = await bindForm("form-guid-0000")
+ * ```
+ *  @see {@link BoundForm}
+ *  @see {@link DOMNodeReference}
+ */
+export default function bindForm(formId: string): Promise<DOMNodeReferenceArray & Record<string, DOMNodeReference>>;