powerpagestoolkit 3.0.3215 → 3.0.4041

package/README.md

@@ -27,10 +27,10 @@ A powerful class for managing DOM elements with automatic value synchronization
 
 #### Basic Usage
 
-PowerPagesElements are instantiated with the help of the following factory function: `createRef`
+PowerPagesElements are instantiated with the help of the following factory function: `get`
 
 ```typescript
-createRef(
+get(
   target: HTMLElement | string,
   options: {
     multiple: (() => boolean) | boolean = false,
@@ -40,7 +40,7 @@ createRef(
 ): Promise<PowerPagesElement | PowerPagesElement[]>;
 ```
 
-createRef takes two main arguments:
+get takes two main arguments:
 
 <table style="width: 100%; border-collapse: collapse;">
   <thead>
@@ -79,17 +79,17 @@ createRef takes two main arguments:
 Import the utility function for creating PowerPagesElement(s)
 
 ```typescript
-import { createRef } from "powerpagestoolkit";
+import { get } from "powerpagestoolkit";
 ```
 
 Instantiate one, or multiple instances of a PowerPagesElement, and optionally configure advanced options
 
 ```javascript
 // Create a single reference (i.e. 'querySelector')
-const node = await createRef("#myElement");
+const node = await get("#myElement");
 
 // Create multiple references (i.e. 'querySelectorAll')
-const nodes = await createRef(".my-class", { multiple: true });
+const nodes = await get(".my-class", { multiple: true });
 
 /******************/
 // ADVANCED OPTIONS
@@ -98,31 +98,31 @@ 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", { timeoutMs:2000 });
+const node2 = await get("#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 });
+const node3 = await get("#target", { root: otherElement });
 
 // implement all options:
-const nodes2 = await createRef("#target", {
+const nodes2 = await get("#target", {
   multiple: true,
-  timeoutMs:4000,
+  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 | PowerPagesElement \| null | Reference to 'yes' radio (for boolean fields) |
-| noRadio  | PowerPagesElement \| null | Reference to 'no' radio (for boolean fields)  |
-| checked  | boolean                  | Checkbox/radio checked state                  |
+| 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 | Radio \| null         | Reference to 'yes' radio (for yes/no fields) |
+| noRadio  | Radio \| null         | Reference to 'no' radio (for yes/no fields)  |
+| checked  | boolean               | Checkbox/radio checked state                 |
 
 #### Key Methods
 
@@ -161,14 +161,14 @@ applyBusinessRule(
 ```typescript
 interface BusinessRule {
   setVisibility?: () => boolean;
-  setRequirements?: () => ({
-    isRequired: () => boolean,
-    isValid: () => boolean
-  });
-  setValue?: () => ({
-    condition: () => boolean,
-    value: () => any | any
-  });
+  setRequirements?: () => {
+    isRequired: () => boolean;
+    isValid: () => boolean;
+  };
+  setValue?: () => {
+    condition: () => boolean;
+    value: () => any | any;
+  };
   setDisabled?: () => boolean;
 }
 ```
@@ -180,10 +180,9 @@ interface BusinessRule {
 // 'businessTypeField' is set to 'Corporation' or 'LLC'
 taxIdField.applyBusinessRule(
   {
-    setVisibility: 
-      () =>
-        businessTypeField.value === "Corporation" ||
-        businessTypeField.value === "LLC"
+    setVisibility: () =>
+      businessTypeField.value === "Corporation" ||
+      businessTypeField.value === "LLC",
   },
   [businessTypeField] // Re-evaluate when businessTypeField changes
 );
@@ -205,7 +204,7 @@ taxIdField.applyBusinessRule(
       isValid: function () {
         return this.value != null && this.value !== "";
       },
-    })
+    }),
   },
   [businessTypeField] // Revalidate when businessTypeField changes
 );
@@ -219,8 +218,8 @@ industryField.applyBusinessRule(
   {
     setValue: () => ({
       condition: () => businessTypeField.value === "Corporation",
-      value: "Corporate"
-    })
+      value: "Corporate",
+    }),
   },
   [businessTypeField] // Apply value when businessTypeField changes
 );
@@ -308,9 +307,9 @@ node.addTooltip(
 _Example:_
 
 ```typescript
-import { createRef } from "powerpagestoolkit";
+import { get } from "powerpagestoolkit";
 
-const title = await createRef("#myTitle");
+const title = await get("#myTitle");
 
 title.addTooltip("This is an Example of a tooltip!", { color: "red" });
 ```
@@ -450,7 +449,7 @@ await API.updateRecord("contacts", "record-guid", {
 1. Always await PowerPagesElement creation:
 
 ```typescript
-const node = await createRef("#element");
+const node = await get("#element");
 ```
 
 2. Include all referenced nodes in dependency arrays:

package/dist/src/ancillary/DOMNodeReference.d.ts

@@ -1,8 +1,8 @@
 /// <reference path="../globals.d.ts" />
+import type EventManager from "../ancillary/EventManager.d.ts";
 import type ValueManager from "../ancillary/ValueManager.d.ts";
-import EventManager from "../ancillary/EventManager.d.ts";
-import VisibilityManager from "./VisibilityManager.d.ts";
-export default class DOMNodeReference {
+import type VisibilityManager from "./VisibilityManager.d.ts";
+export default abstract class DOMNodeReference {
     static instances: DOMNodeReference[];
     [key: symbol]: (...arg: any[]) => any;
     target: Element | string;
@@ -27,16 +27,6 @@ export default class DOMNodeReference {
     visibilityManager: VisibilityManager | null;
     valueManager: ValueManager | null;
     eventManager: EventManager | null;
-    /**
-     * Represents the 'yes' option of a boolean radio field.
-     * This property is only available when the parent node
-     * is a main field for a boolean radio input.
-     */
-    /**
-     * Represents the 'no' option of a boolean radio field.
-     * This property is only available when the parent node
-     * is a main field for a boolean radio input.
-     */
     /**
      * Creates an instance of DOMNodeReference.
      * @param target - The CSS selector to find the desired DOM element.
@@ -44,11 +34,10 @@ export default class DOMNodeReference {
      * Defaults to 'document.body'
      */
     /******/ /******/ constructor(target: Element | string, root: Element | undefined, timeoutMs: number);
+    protected abstract initValueManager(): void;
+    protected abstract initVisibilityManager(): void;
+    protected abstract initEventManager(): void;
     protected _extractLogicalName(target: Element | string): string;
-    /**
-     * Initializes value synchronization with appropriate event listeners
-     * based on element type.
-     */
     protected _valueSync(): void;
     protected _determineEventType(): keyof GlobalEventHandlersEventMap;
     protected _isDateInput(): boolean;
@@ -159,7 +148,7 @@ export default class DOMNodeReference {
      * @param string - The text to set as the inner HTML of the element.
      * @returns - Instance of this [provides option to method chain]
      */
-    setInnerHTML(string: string): this;
+    set innerHTML(innerHTML: string);
     /**
      * Removes this element from the DOM
      * @returns - Instance of this [provides option to method chain]
@@ -170,7 +159,7 @@ export default class DOMNodeReference {
      * @param options - An object containing CSS property-value pairs, e.g., { display: 'block' }.
      * @returns The instance, enabling method chaining.
      */
-    setStyle(options: Partial<CSSStyleDeclaration>): this;
+    setStyle(options: Partial<CSSStyleDeclaration>): DOMNodeReference;
     /**
      * Applies a business rule to manage visibility, required state, value, and disabled state dynamically.
      * @see {@link BusinessRule}
@@ -179,16 +168,10 @@ export default class DOMNodeReference {
      * @returns Instance of this for method chaining.
      */
     applyBusinessRule(rule: BusinessRule, dependencies: DependencyArray<DOMNodeReference>): DOMNodeReference;
-    protected _returnBusinessRuleHandler(rule: BusinessRule): BusinessRuleHandler;
-    protected _createValidator(evaluationFunction: () => boolean): void;
-    /**
-     * Sets up tracking for dependencies using both event listeners and mutation observers.
-     * @protected
-     * @param handler The function to execute when dependencies change
-     * @param dependencies Array of dependent DOM nodes to track
-     * all other options defaults to true
-     */
-    protected _configureDependencyTracking(handler: DependencyHandler, dependencies: DOMNodeReference[]): void;
+    private _setupRequirementsValidator;
+    private _createBusinessRuleHandler;
+    private _createValidator;
+    private _configureDependencyTracking;
     /**
      * Sets the required level for the field by adding or removing the "required-field" class on the label.
      *
@@ -196,7 +179,7 @@ export default class DOMNodeReference {
      * If true, the "required-field" class is added to the label; if false, it is removed.
      * @returns Instance of this [provides option to method chain]
      */
-    setRequiredLevel(isRequired: (() => boolean) | boolean): DOMNodeReference;
+    setRequiredLevel(isRequired: Evaluator | boolean): DOMNodeReference;
     /**
      * Executes a callback function once the element is fully loaded.
      * If the element is already loaded, the callback is called immediately.
@@ -204,5 +187,5 @@ export default class DOMNodeReference {
      * @param callback A callback function to execute once the element is loaded.
      * Receives instance of 'this' as an argument
      */
-    onceLoaded(callback: (instance: DOMNodeReference) => any): any;
+    onceLoaded(callback: (instance: DOMNodeReference) => any): void;
 }

package/dist/src/ancillary/EventManager.d.ts

@@ -9,17 +9,17 @@ declare type Handler = (this: DOMNodeReference, ...args: any[]) => void;
     private observers;
     private boundListeners;
     constructor();
-    dispatchDependencyHandlers(): void;
-    registerDependent(dependency: DOMNodeReference, handler: Handler): true | false;
-    registerEvent(event: EventType, handler: Handler): true | false;
-    registerListener(event: EventType, listener: DOMNodeReference): true | false;
-    emit(eventType: EventType, ...args: any[]): void;
-    stopListening(listener: DOMNodeReference): void;
-    registerObserver(observer: MutationObserver | ResizeObserver, observerOptions: {
+    /********/ dispatchDependencyHandlers(): void;
+    /********/ registerDependent(dependency: DOMNodeReference, handler: Handler): "success" | Error;
+    /********/ registerEvent(event: EventType, handler: Handler): "success" | Error;
+    /********/ registerListener(event: EventType, listener: DOMNodeReference): "success" | Error;
+    /********/ emit(eventType: EventType, ...args: any[]): void;
+    /********/ stopListening(listener: DOMNodeReference): void;
+    /********/ registerObserver(observer: MutationObserver | ResizeObserver, observerOptions: {
         nodeToObserve: Element;
         options: Partial<ResizeObserverOptions> | Partial<MutationObserverInit>;
     }): void;
-    registerDOMEventListener(element: Element, eventType: keyof HTMLElementEventMap, handler: (e: Event) => unknown): void;
-    destroy(): void;
+    /********/ registerDOMEventListener(element: Element, eventType: keyof HTMLElementEventMap, handler: (e: Event) => unknown): void;
+    /********/ destroy(): void;
 }
 export {};

package/dist/src/ancillary/InfoElement.d.ts

@@ -0,0 +1,25 @@
+/// <reference path="../globals.d.ts" />
+/**
+ *
+ * @param {string} titleString The text to display in the tooltip flyout content
+ * @param iconStyle Optional CSS styles to apply to the info icon
+ * @returns
+ */
+/********/ /********/ export default class InfoElement extends HTMLElement {
+    private flyoutContent;
+    private icon;
+    private observers;
+    /********/ constructor(titleString: string, iconStyle?: Partial<CSSStyleDeclaration>);
+    /********/ private attachEventListeners;
+    /********/ private setupObservers;
+    /********/ private getDesiredWidth;
+    /********/ private positionFlyout;
+    /********/ private updateFlyoutWidth;
+    /********/ private handleClick;
+    /********/ private handleResize;
+    /********/ private handleTouchStart;
+    /********/ private handleMouseEnter;
+    /********/ private handleMouseLeave;
+    /********/ private handleScroll;
+    /********/ private destroy;
+}

package/dist/src/ancillary/LoadingSpinner.d.ts

@@ -0,0 +1,16 @@
+/// <reference path="../globals.d.ts" />
+/**
+ * @class LoadingSpinner - instantiate a spinner to handle loading state in your powerpages site
+ */
+/********/ /********/ export default class LoadingSpinner extends HTMLElement {
+    private element;
+    constructor();
+    /**
+     * @method hide - Hides the loading spinner
+     */
+    hide(): void;
+    /**
+     * @method show - Shows the loading spinner
+     */
+    show(): void;
+}

package/dist/src/ancillary/Radio.d.ts

@@ -2,7 +2,10 @@
 import DOMNodeReference from "./DOMNodeReference.d.ts";
 export default class Radio extends DOMNodeReference {
     [key: symbol]: (...arg: any[]) => any;
-    protected radioType: RadioType | null;
+    radioType: RadioType | undefined;
     radioParent: DOMNodeReference | undefined;
     constructor(parent: DOMNodeReference, target: Element | string, root: Element | undefined, timeoutMs: number, radioType: RadioType);
+    protected initEventManager(): void;
+    protected initValueManager(): void;
+    protected initVisibilityManager(): void;
 }

package/dist/src/ancillary/ValueManager.d.ts

@@ -3,11 +3,12 @@ import type DOMNodeReference from "./DOMNodeReference.d.ts";
 export default class ValueManager {
     value: any;
     checked: true | false;
-    private element;
+    element: HTMLElement | null;
     private noRadio;
     private yesRadio;
     radioParent?: DOMNodeReference | undefined;
     private isRadio;
+    private radioType;
     constructor(instance: DOMNodeReference);
     setValue(value: any): void;
     updateValue(e?: Event): Promise<void>;

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

@@ -1,8 +1,9 @@
 /// <reference path="../globals.d.ts" />
 import DOMNodeReference from "../ancillary/DOMNodeReference.d.ts";
 import Radio from "../ancillary/Radio.d.ts";
-export default class PowerPagesElement extends DOMNodeReference {
+/********/ /********/ export default class PowerPagesElement extends DOMNodeReference {
     [key: symbol]: (...arg: any[]) => any;
+    private isMasked;
     /**
      * Represents the 'yes' option of a boolean radio field.
      * This property is only available when the parent node
@@ -21,12 +22,32 @@ export default class PowerPagesElement extends DOMNodeReference {
      * @param root - Optionally specify the element within to search for the element targeted by 'target'
      * Defaults to 'document.body'
      */
-    /******/ /******/ constructor(target: Element | string, root: Element | undefined, timeoutMs: number);
+    /******/ constructor(target: Element | string, root: Element | undefined, timeoutMs: number);
+    protected initValueManager(): void;
+    protected initVisibilityManager(): void;
+    protected initEventManager(): void;
     protected _attachRadioButtons(): Promise<void>;
     clearValue(): void;
     /**
      * Unchecks both the yes and no radio buttons if they exist.
      * @returns - Instance of this [provides option to method chain]
      */
-    uncheckRadios(): DOMNodeReference;
+    uncheckRadios(): PowerPagesElement;
+    /**
+     * Apply an input mask to this element
+     * @param type The type of input mask to apply to this element
+     * @param options The options to specify the behavior of the mask
+     */
+    inputMask(type: "phone" | "money", options: InputMaskOptions): void;
+    inputMask(type: "phone", options?: {
+        format?: PhoneNumberFormats;
+        countryCode?: CountryCodeFormats;
+    }): void;
+    inputMask(type: "money", options?: {
+        prefix?: CurrencySymbol;
+        decimalPlaces?: number;
+        thousandsSeparator?: string;
+        decimalSeparator?: string;
+        allowNegative?: boolean;
+    }): void;
 }

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

@@ -15,43 +15,9 @@ import PowerPagesElement from "./PowerPagesElement.d.ts";
  * @see {@link PowerPagesElementArray}
  * @see {@link enhanceArray}
  */
-export default function createPowerPagesElement(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<PowerPagesElement>;
+export default function createPowerPagesElement(target: string | Element): Promise<PowerPagesElement>;
+export default function createPowerPagesElement(target: Element): Promise<PowerPagesElement>;
 export default function createPowerPagesElement(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<PowerPagesElement>;
-export default function createPowerPagesElement(target: Element, options?: {
     /**
      * Optionally specify the element within which to search for the element targeted by 'target'.
      * Defaults to 'document.body'.

package/dist/src/globals.d.ts

@@ -87,8 +87,8 @@ declare interface BusinessRule {
    * @param isValid.isRequiredResult - Only available if 'isRequired' is also returned from the configuration function
    */
   setRequirements?: () => {
-    isRequired?: (this: PowerPagesElement) => boolean;
-    isValid?: (this: PowerPagesElement, isRequiredResult?: boolean) => boolean;
+    isRequired?: Evaluator<DOMNodeReference>;
+    isValid?: Evaluator<DOMNodeReference, boolean>;
   };
 
   /**
@@ -118,27 +118,6 @@ type NonEmptyArray<T extends unknown[]> = T extends []
 // but if someone passes an empty array (i.e. []), the type becomes a custom error.
 declare type DependencyArray<T> = NonEmptyArray<[T, ...T[]]>;
 
-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;
-}
-
 declare type DependencyHandler = () => void;
 
 declare interface BusinessRuleHandler extends DependencyHandler {}
@@ -173,3 +152,28 @@ declare type FormElement =
   | HTMLSpanElement
   | HTMLButtonElement
   | HTMLFieldSetElement;
+
+declare type PhoneNumberFormats =
+  | "xxx-xxx-xxxx"
+  | "(xxx) xxx-xxxx"
+  | "xxx xxx-xxxx"
+  | "xxx.xxx.xxxx";
+
+declare type CountryCodeFormats = "+" | "()";
+
+declare type CurrencySymbol = "$" | "€" | "£" | "¥" | "¢";
+
+declare interface InputMaskOptions {
+  format?: PhoneNumberFormats;
+  countryCode?: CountryCodeFormats;
+  prefix?: CurrencySymbol; // Currency symbol (e.g., "$")
+  decimalPlaces?: number; // Number of decimal places (default: 2)
+  thousandsSeparator?: string; // Character for separating thousands (e.g., ",")
+  decimalSeparator?: string; // Character for decimal point (e.g., ".")
+  allowNegative?: boolean; // Whether to allow negative values
+}
+
+declare type Evaluator<T = any, A = unknown> = (
+  this: T,
+  ...args: A[]
+) => boolean;

package/dist/src/index.d.ts

@@ -2,4 +2,5 @@ import API from "./core/API.d.ts";
 import get from "./core/getPowerPagesElement.d.ts";
 import waitFor from "./core/waitFor.d.ts";
 import bindForm from "./core/bindForm.d.ts";
-export { API, bindForm, get, waitFor };
+import LoadingSpinner from "./ancillary/LoadingSpinner.d.ts";
+export { API, bindForm, get, waitFor, LoadingSpinner };