powerpagestoolkit 2.3.311 → 2.4.113

package/README.md

@@ -1,317 +1,242 @@
 # 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
+```
+
+## Core Modules
 
-`npm install powerpagestoolkit`
+### DOMNodeReference
 
-You can then import into your JavaScript files as follows:
+A powerful class for managing DOM elements with automatic value synchronization and event handling.
 
-```javascript
+#### Basic Usage
+
+```typescript
 import {
-  API,
   createDOMNodeReference,
   createMultipleDOMNodeReferences,
 } from "powerpagestoolkit";
-```
 
-# Modules
+// Both methods support standard querySelector syntax:
 
-### `DOMNodereference`
+// Create a single reference
+const node = await createDOMNodeReference("#myElement");
 
-The `DOMNodeReference` module simplifies DOM element management. It provides functionalities for creating and interacting with DOM elements:
-
-#### Usage
+// Create multiple references
+const nodes = await createMultipleDOMNodeReferences(".my-class");
+```
 
-- **`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
+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"]');
-
-nodeArray.forEach((node) => {
-    node.oneLoaded(() => {
-        console.log("Element loaded: ", node.element")
-    })
-})
+// Wait for element to be loaded
+node.onceLoaded((instance) => {
+  console.log("Element ready:", instance.element);
+});
 ```
 
-##### Available Properties
-
-These properties are public and can be used in any custom logic/configurations
+##### Visibility Control
 
 ```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;
+// Basic visibility
+node.hide();
+node.show();
+
+// Advanced conditional rendering
+node.configureConditionalRendering(
+  // Function to evaluate wether this node should be visible or not
+  function () {
+    return otherNode.value === "expected";
+  },
+  [otherNode] // Dependency array | if the values or visibility of these change, the function is re-evaluated
+);
 ```
 
-##### Methods
-
-Here are the key methods you can use with a DOMNodeReference instance:
-
-```javascript
-
-/********/
-// VISIBILITY / ACCESSIBILITY
-
-// Hides the associated DOM element.
-hide()
-
-// Shows the associated DOM element.
-show()
-
-/**
- * advanced visibility control in the case you need to apply
- * custom logic to the visibility of an element
- */
-toggleVisibility(shouldShow: boolean | () => boolean)
-
-/**
-  * 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
-        */
-      );
-
-
-/**
- * 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()
-```
+##### Validation and Requirements
 
-```javascript
-// OTHER METHODS
+```typescript
+node.configureValidationAndRequirements(
+  // Function to evaluate if this field should be required
+  function () {
+    return dependentNode.yesRadio?.checked ?? false;
+  },
+  // Function to evaluate if the data in this field is valid
+  function () {
+    return this.value != null && this.value !== "";
+  },
+  "Field Display Name", // the name that will be displayed along side a validation failure message
+  [dependentNode] // Dependency array | if the requirement level of these change, this element is re-evaluated
+);
+```
 
-// Sets the value of the associated HTML element.
-setValue(value: any)
+##### Element Manipulation
 
-// Sets the inner HTML content of the associated HTML element.
-setTextContent(text: string)
+```typescript
+// Value management
+node.setValue("new value"); // set a static value
+// or set a value by using some sort of logic
+node.setValue(() => {
+  if (true) {
+    return "value";
+  } else return "default";
+});
+node.updateValue(); // Sync with DOM
+
+// Content manipulation
+node.setInnerHTML("<span>New content</span>");
+node.append(childElement);
+node.prepend(headerElement);
+node.after(siblingElement);
+node.before(labelElement);
+
+// Styling
+node.setStyle({
+  display: "block",
+  color: "red",
+});
 
-// set any style attribute for 'this' with standard CSS style declaration
-setStyle(options: Partial<CSSStyleDeclaration>): void;
+// State management
+node.disable();
+node.enable();
+```
 
-// Appends child elements to the associated HTML element.
-append(...elements: HTMLElement[])
+##### Label and Tooltip Management
 
-// Inserts elements after the associated HTML element.
-after(...elements: HTMLElement[])
+```typescript
+// LABEL AND INFO OPERATIONS
+const label = node.getLabel();
+node.appendToLabel(infoElement);
+// appends a tooltip to the label associated with the element targeted by 'this'
+node.addLabelTooltip("Helper text");
+// appends a tooltip directly to the element targeted by 'this'
+node.addTooltip("Inline helper");
+```
 
-// Retrieves the label associated with the HTML element.
-getLabel(): HTMLElement | null
+### DataVerse API
 
-// Appends child elements to the label associated with the HTML element.
-appendToLabel(...elements: HTMLElement[])
+Type-safe wrapper for DataVerse API operations.
 
-// Create an event listener on the target element. Provide access to 'this'
-// in the event handler function
-on(eventType: string, eventHandler: (this: DOMNodeReference) => void)
+#### Create Record
 
-// Unchecks both yes and no radio buttons if they exist.
-uncheckRadios()
+```typescript
+const recordId = await API.createRecord("accounts", {
+  name: "New Account",
+  type: "Customer",
+})
+  .then(() => {
+    console.log("Created record:", recordId);
+  })
+  .catch(() => {
+    console.error("Creation failed:", error);
+  });
+```
 
-// Adds a tooltip to the label associated with the HTML element.
-addLabelTooltip(text: string)
+#### Get Records
 
-// Adds a tooltip with the specified text to the element
-addTooltip(text: string)
+```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'
+);
+```
 
-// Executes a callback function once the element is fully loaded.
-onceLoaded(callback: (instance: DOMNodeReference) => void)
+#### Update Record
 
+```typescript
+await API.updateRecord("contacts", "record-guid", {
+  name: "Jane Smith",
+  email: "jane@example.com",
+});
 ```
 
-### `API`
+## Best Practices
 
-The `API` module provides functions for creating and retrieving records from a DataVerse. It includes the following methods:
+1. Always await DOMNodeReference creation:
 
-- **`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.
+```typescript
+const node = await createDOMNodeReference("#element");
+```
 
-- **`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.
+2. Include all referenced nodes in dependency arrays:
 
-#### Usage
+```typescript
+node.configureConditionalRendering(
+  () => dependentNode.value === "test",
+  [dependentNode] // Required!
+);
+```
 
-###### 1. Creating a Record
+3. Use TypeScript for better type safety and IntelliSense support.
 
-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.
+4. Handle loading states:
 
-```javascript
-// Assuming you have a schema class defined
-const schema = new YourSchemaClass({
-  name: "Sample Record",
-  description: "This is a sample record for demonstration.",
+```typescript
+node.onceLoaded((instance) => {
+  // Safe to manipulate the element here
 });
-
-API.createRecord(schema)
-  .then((recordId) => {
-    console.log("Record created successfully with ID:", recordId);
-  })
-  .catch((error) => {
-    console.error("Error creating record:", error);
-  });
 ```
 
-###### 2. Getting a Single Record
+5. Use proper error handling with API operations:
 
-To retrieve a specific record from the DataVerse, use the `getRecord` method. You need to provide the table set name and the record ID.
-
-```javascript
-const tableSetName = "accounts"; // The DataVerse table set name
-const recordID = "your-record-id"; // The GUID of the record to retrieve
-
-API.getRecord(tableSetName, recordID)
-  .then((record) => {
-    console.log("Retrieved record:", record);
-  })
-  .catch((error) => {
-    console.error("Error retrieving record:", error);
-  });
+```typescript
+try {
+  await API.createRecord(/*...*/);
+} catch (error) {
+  // Handle error appropriately
+}
 ```
 
-###### 3. Getting Multiple Records
+## TypeScript Support
 
-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.
+The package includes full TypeScript definitions and type safety. Use TypeScript for the best development experience and catch potential errors at compile time.
 
-```javascript
-const tableSetName = "contacts"; // The DataVerse table set name
-const queryParameters =
-  "$filter=firstName eq 'John'&$select=firstName,lastName"; // OData query parameters
+## Contributing
 
-API.getMultiple(tableSetName, queryParameters)
-  .then((records) => {
-    console.log("Retrieved records:", records);
-  })
-  .catch((error) => {
-    console.error("Error retrieving records:", error);
-  });
-```
-
-##### Example Schema Class
+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.
 
-Here's a simple example of a schema class that you might use with the createRecord method:
+## License
 
-```javascript
-class YourSchemaClass {
-  constructor(tableSetName, data) {
-    this.setName = tableSetName;
-    this.data = data;
-  }
-
-  value() {
-    return JSON.stringify(this.data); // Convert data to JSON format for the API
-  }
-}
-```
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/dist/API.d.ts

@@ -1,10 +1,10 @@
 declare const API: {
     /**
-     *
-     * @param {Schema} schema an instance of a schema class, containing the desired information for the POST request
+     * @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(schema: Schema): Promise<string>;
+    createRecord(tableSetName: string, data: object): Promise<string>;
     /**
      *
      * @param tableSetName The DataVerse SET name of the table being queried

package/dist/bundle.js

@@ -23,16 +23,16 @@ function safeAjax(ajaxOptions) {
 // src/API.ts
 var API = {
   /**
-   *
-   * @param {Schema} schema an instance of a schema class, containing the desired information for the POST request
+   * @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(schema) {
+  createRecord(tableSetName, data) {
     return new Promise((resolve, reject) => {
       safeAjax({
         type: "POST",
-        url: `/_api/${schema.logicalName()}`,
-        data: schema.value(),
+        url: `/_api/${tableSetName}`,
+        data: JSON.stringify(data),
         contentType: "application/json",
         success: function(response, status, xhr) {
           resolve(xhr.getResponseHeader("entityid"));
@@ -277,7 +277,11 @@ var DOMNodeReference = class _DOMNodeReference {
         this.value = this.element.value !== "" ? Number(this.element.value) : null;
         break;
       default:
-        this.value = this.element.value;
+        if (this.element.classList.contains("decimal")) {
+          this.value = parseFloat(this.element.value);
+        } else {
+          this.value = this.element.value;
+        }
         break;
     }
     if (this.yesRadio instanceof _DOMNodeReference) {

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "powerpagestoolkit",
-  "version": "2.3.311",
+  "version": "2.4.113",
   "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/bundle.js",
   "types": "./dist/index.d.ts",
   "scripts": {
     "typecheck": "tsc",
     "node:build": "node build.js",
+    "clean": "rimraf dist",
     "build:types": "tsc --emitDeclarationOnly --declaration",
-    "build": "npm run typecheck && npm run node:build && npm run build:types",
+    "build": "npm run clean && npm run typecheck && npm run node:build && npm run build:types",
     "dev": "tsc --watch"
   },
   "devDependencies": {
@@ -19,6 +20,7 @@
     "esbuild-css-modules-plugin": "^3.1.2",
     "eslint": "^8.57.1",
     "eslint-plugin-import": "^2.31.0",
+    "rimraf": "^6.0.1",
     "ts-loader": "^9.5.1",
     "typescript": "^5.6.3",
     "typescript-eslint": "^8.12.2"
@@ -70,5 +72,8 @@
     "./style.css": {
       "import": "./dist/bundle.css"
     }
+  },
+  "dependencies": {
+    "powerpagestoolkit": "^2.3.4"
   }
 }