powerpagestoolkit 2.7.1 → 2.7.2

package/README.md

@@ -35,7 +35,7 @@ createRef(
   options: {
     multiple: (() => boolean) | boolean = false,
     root: HTMLElement,
-    timeout: number
+    timeoutMs:number
   }
 ): Promise<DOMNodeReference | DOMNodeReference[]>;
 ```
@@ -66,7 +66,7 @@ createRef takes two main arguments:
         <pre><code class="language-javascript">{
   multiple: () => boolean | boolean,
   root: HTMLElement,
-  timeout: number
+  timeoutMs:number
 }</code></pre>
       </td>
       <td style="border: 1px solid #ddd; padding: 8px;">
@@ -85,10 +85,10 @@ import { createRef } from "powerpagestoolkit";
 Instantiate one, or multiple instances of a DOMNodeReference, and optionally configure advanced options
 
 ```javascript
-// Create a single reference
+// Create a single reference (i.e. 'querySelector')
 const node = await createRef("#myElement");
 
-// Create multiple references
+// Create multiple references (i.e. 'querySelectorAll')
 const nodes = await createRef(".my-class", { multiple: true });
 
 /******************/
@@ -98,7 +98,7 @@ const nodes = await createRef(".my-class", { multiple: true });
 
 // If the node you are targeting is not available at the initial execution
 // of the script, set a timeout for 2 seconds
-const node2 = await createRef("#target", { timeout: 2000 });
+const node2 = await createRef("#target", { timeoutMs:2000 });
 
 // need to target a node within a specific node? use that node as the root
 const otherElement = document.getElementById("id");
@@ -107,7 +107,7 @@ const node3 = await createRef("#target", { root: otherElement });
 // implement all options:
 const nodes2 = await createRef("#target", {
   multiple: true,
-  timeout: 4000,
+  timeoutMs:4000,
   root: otherElement,
 });
 ```
@@ -150,7 +150,7 @@ _Method Signature:_
 
 ```typescript
 applyBusinessRule(
-  rule: IBusinessRule,
+  rule: BusinessRule,
   dependencies: DOMNodeReference[]
 ): DOMNodeReference; /* Instance of this is returned for optional
  method chaining */
@@ -159,9 +159,9 @@ applyBusinessRule(
 **BusinessRule Definition**
 
 ```typescript
-interface IBusinessRule {
+interface BusinessRule {
   setVisibility?: [
-    condition: () => boolean, 
+    condition: () => boolean,
     clearValuesOnHide?: boolean = true
     ];
   setRequired?: [
@@ -169,7 +169,7 @@ interface IBusinessRule {
     isValid: () => boolean
   ];
   setValue?: [
-    condition: () => boolean, 
+    condition: () => boolean,
     value: () => any | any
     ];
   setDisabled?: () => boolean;
@@ -192,7 +192,7 @@ taxIdField.applyBusinessRule(
   [businessTypeField] // Re-evaluate when businessTypeField changes
 );
 
-// Optionally disable 'clearValuesOnHide:
+// Optionally disable 'clearValuesOnHide':
 taxIdField.applyBusinessRule(
   {
     setVisibility: [
@@ -234,7 +234,10 @@ taxIdField.applyBusinessRule(
 // Set default industry value when 'businessTypeField' is 'Corporation'
 industryField.applyBusinessRule(
   {
-    setValue: [() => businessTypeField.value === "Corporation", "Corporate"],
+    setValue: [
+      () => businessTypeField.value === "Corporation",
+      "Corporate"
+    ],
   },
   [businessTypeField] // Apply value when businessTypeField changes
 );
@@ -246,7 +249,7 @@ industryField.applyBusinessRule(
 // Disable 'taxIdField' when 'businessTypeField' is 'Individual'
 taxIdField.applyBusinessRule(
   {
-    setDisabled: [() => businessTypeField.value === "Individual"],
+    setDisabled: () => businessTypeField.value === "Individual",
   },
   [businessTypeField] // Enable/disable when businessTypeField changes
 );

package/dist/import_map.json

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,88 @@
+/// <reference path="../globals.d.ts" />
+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 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.
+ *
+ * @see {@link DOMNodeReference}
+ * @see {@link DOMNodeReferenceArray}
+ * @see {@link enhanceArray}
+ */
+export default function createDOMNodeReference(target: string | HTMLElement, options?: {
+    /**
+     * 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;
+}): Promise<DOMNodeReference>;
+export default function createDOMNodeReference(target: string, options?: {
+    /**
+     * Should this call return an array of instantiated references, or just a single?
+     * Defaults to false, returning a single instance.
+     */
+    multiple?: false;
+    /**
+     * 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;
+}): Promise<DOMNodeReference>;
+export default function createDOMNodeReference(target: Element, options?: {
+    /**
+     * 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;
+}): Promise<DOMNodeReference>;
+export default function createDOMNodeReference(target: string, options?: {
+    /**
+     * Should this call return an array of instantiated references, or just a single?
+     * Defaults to false, returning a single instance.
+     */
+    multiple?: true;
+    /**
+     * 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;
+}): Promise<DOMNodeReferenceArray>;
+export declare function validateOptions(options: Partial<CreationOptions>): void;
+export declare function createProxyHandler(): {
+    get: (target: DOMNodeReference, prop: string | symbol) => any;
+};

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

@@ -0,0 +1,9 @@
+/// <reference path="../globals.d.ts" />
+/**
+ * Provides an async way to capture DOM elements; for when querySelector cannot capture the target due to async DOM content loading
+ * @param **target** - basic querySelector syntax to select an element
+ * @param **root** - optional parameter to replace document as the root from which to perform the node search
+ * @returns the element(s) targeted by the `querySelector` string
+ */
+export default function waitFor(target: string, root: Element | Document, multiple: false, debounceTime: number): Promise<HTMLElement>;
+export default function waitFor(target: string, root: Element | Document, multiple: true, debounceTime: number): Promise<HTMLElement[]>;

package/dist/{errors.d.ts → src/errors/errors.d.ts}

@@ -1,4 +1,5 @@
-import DOMNodeReference from "./DOMNodeReference.js";
+/// <reference path="../globals.d.ts" />
+import type DOMNodeReference from "../core/DOMNodeReference.d.ts";
 export declare class DOMNodeInitializationError extends Error {
     constructor(instance: DOMNodeReference, error: string);
 }