powerpagestoolkit 2.221.12 → 2.701.4

package/README.md

@@ -1,317 +1,508 @@
 # PowerPages Tool Kit
 
-This package provides utilities for managing and interacting with the DOM and making AJAX requests to a DataVerse API. It includes the `API` module for handling CRUD operations and the `DOMNodeReference` class for seamless DOM manipulations.
+A TypeScript/JavaScript utility package for seamless DOM manipulation and DataVerse API interactions in PowerPages applications. This toolkit provides robust DOM element management and standardized DataVerse CRUD operations with full TypeScript support.
+
+## Features
+
+- Powerful DOM element manipulation and reference management
+- Type-safe DataVerse API operations
+- Automatic value synchronization for form elements
+- Advanced conditional rendering and validation
+- Radio button and checkbox handling
+- Event management with proper TypeScript typing
+- Mutation observer integration for dynamic content
+- Tooltip and label management utilities
 
 ## Installation
 
-After installing
+```bash
+npm install powerpagestoolkit
+```
 
-`npm install powerpagestoolkit`
+# Core Modules
 
-You can then import into your JavaScript files as follows:
+### DOMNodeReference
 
-```javascript
-import {
-  API,
-  createDOMNodeReference,
-  createMultipleDOMNodeReferences,
-} from "powerpagestoolkit";
+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: `createRef`
+
+```typescript
+createRef(
+  target: HTMLElement | string,
+  options: {
+    multiple: (() => boolean) | boolean = false,
+    root: HTMLElement,
+    timeoutMs:number
+  }
+): Promise<DOMNodeReference | DOMNodeReference[]>;
 ```
 
-# Modules
+createRef takes two main arguments:
+
+<table style="width: 100%; border-collapse: collapse;">
+  <thead>
+    <tr>
+      <th style="border: 1px solid #ddd; padding: 8px; text-align: left;">Property</th>
+      <th style="border: 1px solid #ddd; padding: 8px; text-align: left;">Type</th>
+      <th style="border: 1px solid #ddd; padding: 8px; text-align: left;">Details</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td style="border: 1px solid #ddd; padding: 8px;">target</td>
+      <td style="border: 1px solid #ddd; padding: 8px;">
+        <pre><code class="language-javascript">string | HTMLElement</code></pre>
+      </td>
+      <td style="border: 1px solid #ddd; padding: 8px;">
+        Use standard <code>querySelector</code> syntax to target an element, or elements in the DOM, or pass in an instance of the element itself to create a reference.
+      </td>
+    </tr>
+    <tr>
+      <td style="border: 1px solid #ddd; padding: 8px;">options</td>
+      <td style="border: 1px solid #ddd; padding: 8px;">
+        <pre><code class="language-javascript">{
+  multiple: () => boolean | boolean,
+  root: HTMLElement,
+  timeoutMs:number
+}</code></pre>
+      </td>
+      <td style="border: 1px solid #ddd; padding: 8px;">
+        Provides advanced configurations for niche scenarios, such as async DOM element loading, returning arrays of elements, or specifying the parent to search within for the target node.
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+Import the utility function for creating DOMNodeReference(s)
 
-### `DOMNodereference`
+```typescript
+import { createRef } from "powerpagestoolkit";
+```
 
-The `DOMNodeReference` module simplifies DOM element management. It provides functionalities for creating and interacting with DOM elements:
+Instantiate one, or multiple instances of a DOMNodeReference, and optionally configure advanced options
 
-#### Usage
+```javascript
+// Create a single reference (i.e. 'querySelector')
+const node = await createRef("#myElement");
+
+// Create multiple references (i.e. 'querySelectorAll')
+const nodes = await createRef(".my-class", { multiple: true });
+
+/******************/
+// ADVANCED OPTIONS
+// in the event that you need to be more granular with how you are targeting
+// and retrieving elements, there are additional options
+
+// 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", { timeoutMs:2000 });
+
+// need to target a node within a specific node? use that node as the root
+const otherElement = document.getElementById("id");
+const node3 = await createRef("#target", { root: otherElement });
+
+// implement all options:
+const nodes2 = await createRef("#target", {
+  multiple: true,
+  timeoutMs:4000,
+  root: otherElement,
+});
+```
 
-- **`createDOMNodeReference(selector)`**: Creates a `DOMNodeReference` instance for a single DOM element specified by a CSS selector or HTMLElement. Returns a `DOMNodeReference` instance.
+#### Properties
 
-- **`createMultipleDOMNodeReferences(selector)`**: Creates multiple `DOMNodeReference` instances for all elements matching the specified CSS selector. Returns an array of `DOMNodeReference` instances.
+| Property | Type                     | Description                                   |
+| -------- | ------------------------ | --------------------------------------------- |
+| element  | HTMLElement              | The referenced DOM element                    |
+| value    | any                      | Current synchronized value of the element     |
+| isLoaded | boolean                  | Element load status                           |
+| target   | HTMLElement \| string    | Original target selector or element           |
+| yesRadio | DOMNodeReference \| null | Reference to 'yes' radio (for boolean fields) |
+| noRadio  | DOMNodeReference \| null | Reference to 'no' radio (for boolean fields)  |
+| checked  | boolean                  | Checkbox/radio checked state                  |
 
-`selector` uses standard ED6 `document.querySelector()` syntax. For more information, read [here](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector)
+#### Key Methods
 
-```javascript
-// single instance of DOMNodeReference
-const node = await createDOMNodeReference("#my-element");
+##### Event Handling
 
-node.onceLoaded(() => {
-  console.log("Element is loaded: ", node.element);
+```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);
 });
 
-// to imitate 'querySelectorAll', and return an array of DOMNodeReferences
-const nodeArray = await createMultipleDOMNodeReferences('div[class="row"]');
+node.on("click", function (e) {
+  console.log(this, " has been clicked");
+});
 
-nodeArray.forEach((node) => {
-    node.oneLoaded(() => {
-        console.log("Element loaded: ", node.element")
-    })
-})
+...
 ```
 
-##### Available Properties
+##### Business Rule Application
+
+This utility provides a flexible way to dynamically control field visibility, requirement status, values, and enabled states based on dependencies within PowerPages forms.
 
-These properties are public and can be used in any custom logic/configurations
+_Method Signature:_
 
 ```typescript
-target: HTMLElement | string;
-element: HTMLElement;
-isLoaded: boolean;
-value: any;
-/**
- * If the element targeted is the main input for a yes/no radio control,
- * yesRadio and noRadio will be available as properties of 'this'
- */
-yesRadio: DOMNodeReference;
-noRadio: DOMNodeReference;
-// and if 'this' is the instance of a yesRadio or noRadio
-// checked will represent wether the radio has been checked or not
-checked: boolean;
+applyBusinessRule(
+  rule: BusinessRule,
+  dependencies: DOMNodeReference[]
+): DOMNodeReference; /* Instance of this is returned for optional
+ method chaining */
 ```
 
-##### Methods
+**BusinessRule Definition**
 
-Here are the key methods you can use with a DOMNodeReference instance:
+```typescript
+interface BusinessRule {
+  setVisibility?: [
+    condition: () => boolean,
+    clearValuesOnHide?: boolean = true
+    ];
+  setRequired?: [
+    isRequired: () => boolean,
+    isValid: () => boolean
+  ];
+  setValue?: [
+    condition: () => boolean,
+    value: () => any | any
+    ];
+  setDisabled?: () => boolean;
+}
+```
 
-```javascript
+##### Visibility Control
 
-/********/
-// VISIBILITY / ACCESSIBILITY
+```typescript
+// Show the 'taxIdField' only when
+// 'businessTypeField' is set to 'Corporation' or 'LLC'
+taxIdField.applyBusinessRule(
+  {
+    setVisibility: [
+      () =>
+        businessTypeField.value === "Corporation" ||
+        businessTypeField.value === "LLC",
+    ],
+  },
+  [businessTypeField] // Re-evaluate when businessTypeField changes
+);
+
+// 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
+);
+```
 
-// Hides the associated DOM element.
-hide()
+##### Validation and Requirements
 
-// Shows the associated DOM element.
-show()
+```typescript
+// 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
+);
+```
 
-/**
- * advanced visibility control in the case you need to apply
- * custom logic to the visibility of an element
- */
-toggleVisibility(shouldShow: boolean | () => boolean)
+##### Setting Field Values Conditionally
 
-/**
-  * 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.
-  */
-configureConditionalRendering(
-  condition: (this: DOMNodeReference) => boolean,
-  dependencies: Array<DOMNodeReference>
-  )
-
-
-    // EXAMPLE:
-    const your_node = await createDOMNodeReference("#element_id")
-    const other_node = await createDOMNodeReference(".element_class")
-
-    your_node.configureConditionalRendering(() =>
-        other_node.value == "3",
-        /* your_node will only be
-        visible when the value of other_node is "3"
-        */
-        [other_node]
-        /* and we have to include any DOMNodeReferences used
-        in the evaluation logic, so that changes to them can
-        be watched and the condition evaluated again
-        */
-      );
+```typescript
+// Set default industry value when 'businessTypeField' is 'Corporation'
+industryField.applyBusinessRule(
+  {
+    setValue: [
+      () => businessTypeField.value === "Corporation",
+      "Corporate"
+    ],
+  },
+  [businessTypeField] // Apply value when businessTypeField changes
+);
+```
 
+##### Enabling and Disabling Fields
 
-/**
- * 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.
- * Return `true` if required, `false` to not be required.
- * @param {function(this: DOMNodeReference): boolean} isValid
- * A function that checks if the field's input is valid.
- * Return `true` if validation satisfied, `false` if not.
- * @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 Nodes or their values 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>
-)
-
-    // EXAMPLE:
-    const your_node = await createDOMNodeReference("#element_id")
-    const other_node = await createDOMNodeReference(".element_class")
-
-    your_node.configureValidationAndRequirements(
-        () => other_node.yesRadio.checked,
-        /* if 'yes' is checked for this other node,
-          this function will evaluate to true,
-          meaning that 'your_node' will be required */
-
-        function () {
-          /* important to use standard 'function' declaration,
-            instead of arrow function when needing to
-            access 'this' (the instance of 'your_node') */
-
-          if (other_node.yesRadio.checked) {
-            // when other_node radio is checked 'yes'
-            return this.value; // this is only 'valid' if it has a value
-          } else return true;
-        },
-        "Your Field Name",
-        [other_node]
-        /* since our conditions depend on
-          'other_node' it must be included in the dependency
-          array so that the requirement conditions can be
-          re-evaluated when the value of 'other_node' changes */
-      );
-
-
-/* sets the elements 'disabled' to true - useful for inputs
-that need to be enabled/disabled conditionally */
-disable()
-
-// Sets the element 'disabled' to false
-enable()
+```typescript
+// Disable 'taxIdField' when 'businessTypeField' is 'Individual'
+taxIdField.applyBusinessRule(
+  {
+    setDisabled: () => businessTypeField.value === "Individual",
+  },
+  [businessTypeField] // Enable/disable when businessTypeField changes
+);
 ```
 
-```javascript
-// OTHER METHODS
+##### Element Manipulation
+
+_Value management_
 
-// Sets the value of the associated HTML element.
-setValue(value: any)
+```typescript
+// 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";
+});
 
-// Sets the inner HTML content of the associated HTML element.
-setTextContent(text: string)
+// Sync with DOM
+node.updateValue();
 
-// set any style attribute for 'this' with standard CSS style declaration
-setStyle(options: Partial<CSSStyleDeclaration>): void;
+// Clear the value for both the instance and the target element
+node.clearValue();
+```
 
-// Appends child elements to the associated HTML element.
-append(...elements: HTMLElement[])
+_Content manipulation_
 
-// Inserts elements after the associated HTML element.
-after(...elements: HTMLElement[])
+```typescript
+node.setInnerHTML("<span>New content</span>");
+node.append(childElement);
+node.prepend(headerElement);
+node.after(siblingElement);
+node.before(labelElement);
+```
 
-// Retrieves the label associated with the HTML element.
-getLabel(): HTMLElement | null
+_Styling_
 
-// Appends child elements to the label associated with the HTML element.
-appendToLabel(...elements: HTMLElement[])
+```typescript
+node.setStyle({
+  display: "block",
+  color: "red",
+});
+```
+
+_Enabling/Disabling inputs_
+
+```typescript
+node.disable();
+node.enable();
+```
 
-// Create an event listener on the target element. Provide access to 'this'
-// in the event handler function
-on(eventType: string, eventHandler: (this: DOMNodeReference) => void)
+##### Label and Tooltip Management
 
-// Unchecks both yes and no radio buttons if they exist.
-uncheckRadios()
+```typescript
+// LABEL AND INFO OPERATIONS
+const label = node.getLabel();
+// appends a tooltip to the label associated with the element targeted by 'this'
+node.addLabelTooltip(
+  "Helper text",
+  /* Optionally pass in css styles to customize the tooltip icon*/
+  { color: "orange", fontSize: "30px" }
+);
+// appends a tooltip directly to the element targeted by 'this'
+node.addTooltip(
+  "Inline helper",
+  /* Optionally pass in css styles to customize the tooltip icon*/
+  { color: "orange", fontSize: "30px" }
+);
+```
 
-// Adds a tooltip to the label associated with the HTML element.
-addLabelTooltip(text: string)
+_Example:_
 
-// Adds a tooltip with the specified text to the element
-addTooltip(text: string)
+```typescript
+import { createRef } from "powerpagestoolkit";
 
-// Executes a callback function once the element is fully loaded.
-onceLoaded(callback: (instance: DOMNodeReference) => void)
+const title = await createRef("#myTitle");
 
+title.addTooltip("This is an Example of a tooltip!", { color: "red" });
 ```
 
-### `API`
+![Example](./assets//infoIconExample.gif)
+
+Here's an improved markdown documentation with more comprehensive details:
+
+### BindForm Method
 
-The `API` module provides functions for creating and retrieving records from a DataVerse. It includes the following methods:
+The `bindForm` method simplifies form element management in DataVerse by providing a semantic and efficient way to access form controls, sections, and tabs.
 
-- **`createRecord(schema)`**: Creates a new record in the DataVerse using the provided schema instance. Returns a Promise that resolves with the record ID or rejects with an error.
-- **`getRecord(tableSetName, recordID, selectColumns)`**: Retrieves a specific record from the DataVerse. Returns a Promise that resolves with the retrieved record or rejects with an error.
+##### Key Features
 
-- **`getMultiple(tableSetName, queryParameters)`**: Retrieves multiple records from the DataVerse based on specified query parameters. Returns a Promise that resolves with the list of retrieved records or rejects with an error.
+- Retrieves form definition directly from DataVerse
+- Automatically generates references for:
+  - Controls
+  - Sections
+  - Tabs
 
-#### Usage
+##### Element Types
 
-###### 1. Creating a Record
+| 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 |
 
-To create a new record in the DataVerse, you can use the `createRecord` method. This method takes an instance of a schema class containing the data for the record.
+##### Usage Example
 
 ```javascript
-// Assuming you have a schema class defined
-const schema = new YourSchemaClass({
-  name: "Sample Record",
-  description: "This is a sample record for demonstration.",
+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");
 });
+```
 
-API.createRecord(schema)
-  .then((recordId) => {
-    console.log("Record created successfully with ID:", recordId);
+##### 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("Error creating record:", error);
+    console.error("Form binding failed", error);
   });
 ```
 
-###### 2. Getting a Single Record
+### DataVerse API
 
-To retrieve a specific record from the DataVerse, use the `getRecord` method. You need to provide the table set name and the record ID.
+Perform secure API calls to DataVerse from your PowerPages site. This method implements the shell deferred token to send requests with `__RequestVerificationToken`
 
-```javascript
-const tableSetName = "accounts"; // The DataVerse table set name
-const recordID = "your-record-id"; // The GUID of the record to retrieve
+#### Create Records
 
-API.getRecord(tableSetName, recordID)
-  .then((record) => {
-    console.log("Retrieved record:", record);
+```typescript
+await API.createRecord("accounts", {
+  name: "Gypsum LLC",
+  type: "Vendor",
+})
+  .then((recordId) => {
+    console.log("Created record:", recordId);
   })
   .catch((error) => {
-    console.error("Error retrieving record:", error);
+    console.error("Creation failed:", error);
   });
 ```
 
-###### 3. Getting Multiple Records
+#### Get Records
 
-If you need to retrieve multiple records with specific query parameters, you can use the `getMultiple` method. This method accepts the table set name and optional query parameters for filtering.
+```typescript
+// Single record
+const record = await API.getRecord(
+  "accounts",
+  "record-guid",
+  "select=name,accountnumber"
+);
+
+// Multiple records
+const records = await API.getMultiple(
+  "contacts",
+  '$filter=firstname eq "Jane"&$select=firstname,lastname'
+);
+```
 
-```javascript
-const tableSetName = "contacts"; // The DataVerse table set name
-const queryParameters =
-  "$filter=firstName eq 'John'&$select=firstName,lastName"; // OData query parameters
+#### Update Record
 
-API.getMultiple(tableSetName, queryParameters)
-  .then((records) => {
-    console.log("Retrieved records:", records);
-  })
+```typescript
+await API.updateRecord("contacts", "record-guid", {
+  name: "Jane Smith",
+  email: "jane@example.com",
+});
+```
+
+## Best Practices
+
+1. Always await DOMNodeReference creation:
+
+```typescript
+const node = await createRef("#element");
+```
+
+2. Include all referenced nodes in dependency arrays:
+
+```typescript
+node.configureConditionalRendering(
+  () => dependentNode.value === "test",
+  [dependentNode] // Required!
+);
+```
+
+3. Use TypeScript for better type safety and IntelliSense support.
+
+4. Use proper error handling with API operations:
+
+```typescript
+/* optionally await */ API.createRecord(/*...*/)
+  .then((recordId) => {})
   .catch((error) => {
-    console.error("Error retrieving records:", error);
+    // handle your errors appropriately
   });
 ```
 
-##### Example Schema Class
+## TypeScript Support
 
-Here's a simple example of a schema class that you might use with the createRecord method:
+The package includes full TypeScript definitions and type safety. Use TypeScript for the best development experience and catch potential errors at compile time.
 
-```javascript
-class YourSchemaClass {
-  constructor(tableSetName, data) {
-    this.setName = tableSetName;
-    this.data = data;
-  }
+## Contributing
 
-  value() {
-    return JSON.stringify(this.data); // Convert data to JSON format for the API
-  }
-}
-```
+Contributions are welcome, feel free to create a pull request with enhancements. Please include an explanation of the changes made. All pull requests will be reviewed by the project owner.
+
+## License
+
+This project is licensed under the AGPL-3.0 License - see the [LICENSE](LICENSE) file for details.
+
+## Funding
+
+If you like this project, found it useful, or would like to help support the long-term support of this package, please feel free to contribute via GitHub Sponsors: [Keaton-Brewster](https://github.com/sponsors/Keaton-Brewster)