powerpagestoolkit 2.7.1403 → 2.7.1414

package/dist/README.md

@@ -0,0 +1,508 @@
+# PowerPages Tool Kit
+
+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
+
+```bash
+npm install powerpagestoolkit
+```
+
+# Core Modules
+
+### 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: `createRef`
+
+```typescript
+createRef(
+  target: HTMLElement | string,
+  options: {
+    multiple: (() => boolean) | boolean = false,
+    root: HTMLElement,
+    timeoutMs:number
+  }
+): Promise<DOMNodeReference | DOMNodeReference[]>;
+```
+
+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)
+
+```typescript
+import { createRef } from "powerpagestoolkit";
+```
+
+Instantiate one, or multiple instances of a DOMNodeReference, and optionally configure advanced options
+
+```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,
+});
+```
+
+#### Properties
+
+| 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                  |
+
+#### Key Methods
+
+##### Event Handling
+
+```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);
+});
+
+node.on("click", function (e) {
+  console.log(this, " has been clicked");
+});
+
+...
+```
+
+##### 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.
+
+_Method Signature:_
+
+```typescript
+applyBusinessRule(
+  rule: BusinessRule,
+  dependencies: DOMNodeReference[]
+): DOMNodeReference; /* Instance of this is returned for optional
+ method chaining */
+```
+
+**BusinessRule Definition**
+
+```typescript
+interface BusinessRule {
+  setVisibility?: [
+    condition: () => boolean,
+    clearValuesOnHide?: boolean = true
+    ];
+  setRequired?: [
+    isRequired: () => boolean,
+    isValid: () => boolean
+  ];
+  setValue?: [
+    condition: () => boolean,
+    value: () => any | any
+    ];
+  setDisabled?: () => boolean;
+}
+```
+
+##### Visibility Control
+
+```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
+);
+```
+
+##### Validation and Requirements
+
+```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
+);
+```
+
+##### Setting Field Values Conditionally
+
+```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
+
+```typescript
+// Disable 'taxIdField' when 'businessTypeField' is 'Individual'
+taxIdField.applyBusinessRule(
+  {
+    setDisabled: () => businessTypeField.value === "Individual",
+  },
+  [businessTypeField] // Enable/disable when businessTypeField changes
+);
+```
+
+##### Element Manipulation
+
+_Value management_
+
+```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";
+});
+
+// Sync with DOM
+node.updateValue();
+
+// Clear the value for both the instance and the target element
+node.clearValue();
+```
+
+_Content manipulation_
+
+```typescript
+node.setInnerHTML("<span>New content</span>");
+node.append(childElement);
+node.prepend(headerElement);
+node.after(siblingElement);
+node.before(labelElement);
+```
+
+_Styling_
+
+```typescript
+node.setStyle({
+  display: "block",
+  color: "red",
+});
+```
+
+_Enabling/Disabling inputs_
+
+```typescript
+node.disable();
+node.enable();
+```
+
+##### Label and Tooltip Management
+
+```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" }
+);
+```
+
+_Example:_
+
+```typescript
+import { createRef } from "powerpagestoolkit";
+
+const title = await createRef("#myTitle");
+
+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`
+
+#### Create Records
+
+```typescript
+await API.createRecord("accounts", {
+  name: "Gypsum LLC",
+  type: "Vendor",
+})
+  .then((recordId) => {
+    console.log("Created record:", recordId);
+  })
+  .catch((error) => {
+    console.error("Creation failed:", error);
+  });
+```
+
+#### Get Records
+
+```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'
+);
+```
+
+#### Update Record
+
+```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) => {
+    // handle your errors appropriately
+  });
+```
+
+## TypeScript Support
+
+The package includes full TypeScript definitions and type safety. Use TypeScript for the best development experience and catch potential errors at compile time.
+
+## Contributing
+
+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)

package/dist/import_map.json

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

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

@@ -1,10 +1,15 @@
-declare const API: {
+/**
+ * @module API
+ * Provides an abstract class API that allows basic create, read, and update operations
+ * via the PowerPages API
+ */
+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: object): Promise<string>;
     /**
      *
      * @param tableSetName The DataVerse SET name of the table being queried
@@ -12,14 +17,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 +32,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_n/types → dist/src}/core/DOMNodeReference.d.ts

@@ -1,45 +1,4 @@
-import * as s from "../constants/symbols.ts";
-declare interface ElementValue {
-    value: any;
-    checked?: boolean;
-}
-declare type RadioType = "truthy" | "falsy";
-declare interface BoundEventListener {
-    element: Element;
-    event: keyof HTMLElementEventMap;
-    handler: (e: Event) => unknown;
-}
-declare type FormElement = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement | HTMLSpanElement | HTMLButtonElement | HTMLFieldSetElement;
-declare type BusinessRule = {
-    /**
-     * @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.
-     */
-    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 | 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?: () => boolean;
-};
+import * as s from "../constants/symbols.d.ts";
 export default class DOMNodeReference {
     target: Element | string;
     logicalName?: string;
@@ -292,4 +251,3 @@ export default class DOMNodeReference {
      */
     onceLoaded(callback: (instance: DOMNodeReference) => any): any;
 }
-export {};

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

@@ -1,4 +1,4 @@
-import type DOMNodeReference from "./DOMNodeReference.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.

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

@@ -0,0 +1,28 @@
+/**
+ * @module
+ * This module provides the bindForm function. 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 DOMNodeReferences that represent all fields, sections, sub-grids, and tabs of the given form.
+ * @see {@link DOMNodeReference}
+ * Access these properties of the BoundForm {@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
+ */
+/**
+ * Get all controls related to the form for manipulating with the
+ * DOMNodeReference class. Rather than having to instantiate each fields that you need manually,
+ * you can call this method once with the form ID and gain access to all fields
+ * @param formId - The string GUID of the form you want to bind to
+ * @callback `callbackFn` - Function to execute after the form has been retrieved and bound; the form itself is provided as the argument
+ * @returns An array of DOMNodeReferences, accessible as properties of a Record<string, DOMNodeReference> i.e. formProp = form["some_logicalName"]
+ * @example
+ * ```js
+ * bindForm("some-guid-0000", (form) => {
+ *    //...use the form
+ *    const field = form["field_logical_name"]
+ *    // or
+ *    form["other_logical_name"].someMethod()
+ * })
+ * ```
+ *  @see {@link BoundForm}
+ */
+export default function bindForm(formId: string, callbackFn: (form: BoundForm) => void): Promise<BoundForm>;

package/{dist_n/types → dist/src}/core/createDOMNodeReferences.d.ts

@@ -1,31 +1,18 @@
-import DOMNodeReference from "./DOMNodeReference.ts";
-import type DOMNodeReferenceArray from "./DOMNodeReferenceArray.ts";
-declare interface CreationOptions {
-    /**
-     * Should this call return an array of instantiated references, or just a single?
-     * Defaults to false, returning a single instance.
-     */
-    multiple?: (() => boolean) | boolean;
-    /**
-     * Optionally specify the element within which to search for the element targeted by 'target'.
-     * Defaults to 'document.body'.
-     */
-    root?: HTMLElement;
-    /**
-     * Optionally specify the amount of time that should be waited to find the targeted element before throwing an error.
-     * Useful for async DOM loading. Relies on MutationObserver.
-     * WARNING: Implementing multiple references with timeout can result in infinite loading.
-     */
-    timeoutMs?: number;
-}
+/**
+ * @module createRef
+ * Provides a factory function for creating new DOMNodeReferences
+ * @see {@link DOMNodeReference}
+ */
+import DOMNodeReference from "./DOMNodeReference.d.ts";
+import type DOMNodeReferenceArray from "./DOMNodeReferenceArray.d.ts";
 /**
  * Creates and initializes a DOMNodeReference instance.
  * @see {@link CreationOptions}
- * @param  target The CSS selector for the desired DOM element, or, optionally, the element itself for which to create a DOMNodeReference.
- * @param options Options for advanced retrieval of elements
- * @param options.multiple - Should this call return an array of instantiated references, or just a single? Defaults to false, returning a single instance
- * @param options.root - Optionally specify the element within to search for the element targeted by 'target'. Defaults to 'document.body'
- * @param options.timeoutMs - Optionally specify the amount of time that should be waited to find the targeted element before throwing error - useful for async DOM loading. Relies on MutationObserver.  ***WARNING***: Implementing multiple references with timeout can result in infinite loading.
+ * @param  **target** - The selector, using `querySelector` syntax, for the desired DOM element. Or, the `HTMLElement` itself for which to create a DOMNodeReference.
+ * @param **options** - Options for advanced retrieval of elements
+ * @param **options.multiple** - Should this call return an array of instantiated references, or just a single? Defaults to false, returning a single instance
+ * @param **options.root** - Optionally specify the element within to search for the element targeted by 'target'. Defaults to `document.body`
+ * @param **options.timeoutMs** - Optionally specify the amount of time that should be waited to find the targeted element before throwing error - useful for async DOM loading. Relies on MutationObserver.  ***WARNING***: Implementing multiple references with timeout can result in infinite loading.
  * @returns  A promise that resolves to a Proxy of the initialized DOMNodeReference instance.
  */
 export default function createDOMNodeReference(target: string | HTMLElement, options?: {
@@ -99,4 +86,3 @@ export declare function validateOptions(options: Partial<CreationOptions>): void
 export declare function createProxyHandler(): {
     get: (target: DOMNodeReference, prop: string | symbol) => any;
 };
-export {};