powerpagestoolkit 2.2.0 → 2.3.4

package/README.md

@@ -1,317 +1,234 @@
 # 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
+// Create a single reference
+const node = await createDOMNodeReference("#myElement");
 
-### `DOMNodereference`
-
-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 () {
+    return otherNode.value === "expected";
+  },
+  [otherNode] // Dependencies that trigger re-evaluation
+);
 ```
 
-##### 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(
+  // Required condition
+  function () {
+    return dependentNode.yesRadio?.checked ?? false;
+  },
+  // Validation condition
+  function () {
+    return this.value != null && this.value !== "";
+  },
+  "Field Display Name",
+  [dependentNode] // Dependencies
+);
+```
 
-// 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");
+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 operations
+const label = node.getLabel();
+node.appendToLabel(infoElement);
+node.addLabelTooltip("Helper text");
+node.addTooltip("Inline helper");
+
+// Required state
+node.setRequiredLevel(true);
+```
 
-// 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/DOMNodeReference.d.ts

@@ -40,7 +40,6 @@ export declare const _init: unique symbol;
     [_init](): Promise<void>;
     private _initValueSync;
     updateValue(): void;
-    private _observeValueChanges;
     private _attachVisibilityController;
     private _attachRadioButtons;
     /**
@@ -71,12 +70,12 @@ export declare const _init: unique symbol;
     toggleVisibility(shouldShow: Function | boolean): DOMNodeReference;
     /**
      * Sets the value of the HTML element.
-     * @param {() => any} value - The value to set for the HTML element.
+     * @param {(() => any) | any} value - The value to set for the HTML element.
      * for parents of boolean radios, pass true or false as value, or
      * an expression returning a boolean
      * @returns - Instance of this
      */
-    setValue(value: any): DOMNodeReference;
+    setValue(value: (() => any) | any): DOMNodeReference;
     /**
      * Disables the element so that users cannot input any data
      * @returns - Instance of this
@@ -182,11 +181,11 @@ export declare const _init: unique symbol;
     /**
      * Sets the required level for the field by adding or removing the "required-field" class on the label.
      *
-     * @param {boolean} isRequired - Determines whether the field should be marked as required.
+     * @param {Function | boolean} isRequired - Determines whether the field should be marked as required.
      * If true, the "required-field" class is added to the label; if false, it is removed.
      * @returns - Instance of this
      */
-    setRequiredLevel(isRequired: Function | boolean): DOMNodeReference;
+    setRequiredLevel(isRequired: (() => boolean) | boolean): DOMNodeReference;
     /**
      * Executes a callback function once the element is fully loaded.
      * If the element is already loaded, the callback is called immediately.

package/dist/bundle.css

@@ -0,0 +1,35 @@
+/* src/style.css */
+.info-icon {
+  position: relative;
+  display: inline-block;
+}
+.info-icon .fa-info-circle {
+  cursor: pointer;
+}
+.info-icon .flyout-content {
+  max-width: calc(100vw - 20px);
+  display: none;
+  position: absolute;
+  left: 50%;
+  transform: translateX(-50%);
+  background-color: #f9f9f9;
+  padding: 10px;
+  border: 1px solid #ddd;
+  z-index: 1;
+  min-width: 200px;
+  box-shadow: 0px 4px 8px rgba(0, 0, 0, 0.1);
+  border-radius: 4px;
+}
+@media (max-width: 600px) {
+  .info-icon .flyout-content {
+    max-width: 95vw;
+    padding: 12px;
+    font-size: 0.9em;
+    display: block;
+    right: auto;
+  }
+}
+.required-field::after {
+  content: " *" !important;
+  color: #f00 !important;
+}

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"));
@@ -270,6 +270,9 @@ var DOMNodeReference = class _DOMNodeReference {
           this.element.selectedOptions
         ).map((option) => option.value);
         break;
+      case "select-one":
+        this.value = this.element.value;
+        break;
       case "number":
         this.value = this.element.value !== "" ? Number(this.element.value) : null;
         break;
@@ -281,19 +284,8 @@ var DOMNodeReference = class _DOMNodeReference {
       this.yesRadio.updateValue();
       this.noRadio.updateValue();
       this.checked = this.yesRadio.checked;
-      this.value = this.yesRadio?.checked ? 1 : 0;
+      this.value = this.yesRadio.checked;
     }
-    this._observeValueChanges();
-  }
-  // Add a method to observe value changes using MutationObserver
-  _observeValueChanges() {
-    const observer = new MutationObserver(() => {
-      this.updateValue();
-    });
-    observer.observe(this.element, {
-      attributes: true,
-      attributeFilter: ["value"]
-    });
   }
   _attachVisibilityController() {
     this.visibilityController = this.element;
@@ -366,12 +358,15 @@ var DOMNodeReference = class _DOMNodeReference {
   }
   /**
    * Sets the value of the HTML element.
-   * @param {() => any} value - The value to set for the HTML element.
+   * @param {(() => any) | any} value - The value to set for the HTML element.
    * for parents of boolean radios, pass true or false as value, or
    * an expression returning a boolean
    * @returns - Instance of this
    */
   setValue(value) {
+    if (value instanceof Function) {
+      value = value();
+    }
     if (this.element.classList.contains("boolean-radio")) {
       this.yesRadio.element.checked = value;
       this.noRadio.element.checked = !value;
@@ -609,7 +604,7 @@ var DOMNodeReference = class _DOMNodeReference {
   /**
    * Sets the required level for the field by adding or removing the "required-field" class on the label.
    *
-   * @param {boolean} isRequired - Determines whether the field should be marked as required.
+   * @param {Function | boolean} isRequired - Determines whether the field should be marked as required.
    * If true, the "required-field" class is added to the label; if false, it is removed.
    * @returns - Instance of this
    */
@@ -697,4 +692,11 @@ export {
   createDOMNodeReference,
   createMultipleDOMNodeReferences
 };
-//# sourceMappingURL=bundle.js.map
+
+
+          (function() {
+            const style = document.createElement('style');
+            style.textContent = "/* src/style.css */\n.info-icon {\n  position: relative;\n  display: inline-block;\n}\n.info-icon .fa-info-circle {\n  cursor: pointer;\n}\n.info-icon .flyout-content {\n  max-width: calc(100vw - 20px);\n  display: none;\n  position: absolute;\n  left: 50%;\n  transform: translateX(-50%);\n  background-color: #f9f9f9;\n  padding: 10px;\n  border: 1px solid #ddd;\n  z-index: 1;\n  min-width: 200px;\n  box-shadow: 0px 4px 8px rgba(0, 0, 0, 0.1);\n  border-radius: 4px;\n}\n@media (max-width: 600px) {\n  .info-icon .flyout-content {\n    max-width: 95vw;\n    padding: 12px;\n    font-size: 0.9em;\n    display: block;\n    right: auto;\n  }\n}\n.required-field::after {\n  content: \" *\" !important;\n  color: #f00 !important;\n}\n";
+            document.head.appendChild(style);
+          })();
+        

package/dist/index.d.ts

@@ -1,4 +1,4 @@
+import './style.css';
 import API from "./API.js";
 import { createDOMNodeReference, createMultipleDOMNodeReferences } from "./createDOMNodeReferences.js";
-import "./style.css";
 export { API, createDOMNodeReference, createMultipleDOMNodeReferences };

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "powerpagestoolkit",
-  "version": "2.2.0",
+  "version": "2.3.4",
   "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",
-    "build": "node build.js",
+    "node:build": "node build.js",
+    "clean": "rimraf dist",
     "build:types": "tsc --emitDeclarationOnly --declaration",
-    "build:all": "npm run typecheck && npm run 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"
@@ -55,6 +57,7 @@
   ],
   "files": [
     "dist/bundle.js",
+    "dist/bundle.css",
     "dist/**/*.d.ts"
   ],
   "exports": {
@@ -65,6 +68,9 @@
     "./createDOMNodeReference": {
       "import": "./dist/createDOMNodeReference.js",
       "types": "./dist/createDOMNodeReference.d.ts"
+    },
+    "./style.css": {
+      "import": "./dist/bundle.css"
     }
   }
 }