powerpagestoolkit 2.7.0 → 2.7.1

package/README.md

@@ -142,76 +142,113 @@ node.on("click", function (e) {
 ...
 ```
 
-##### Visibility Control
+##### Business Rule Application
 
-```typescript
-// Basic visibility
-node.hide();
-node.show();
-```
+This utility provides a flexible way to dynamically control field visibility, requirement status, values, and enabled states based on dependencies within PowerPages forms.
 
-**_Advanced conditional rendering_**
+_Method Signature:_
 
-Out of the box, Microsoft does not provide PowerPages developers the ability to hide or show fields or form elements based on the value of another field. This method allows such configurations
+```typescript
+applyBusinessRule(
+  rule: IBusinessRule,
+  dependencies: DOMNodeReference[]
+): DOMNodeReference; /* Instance of this is returned for optional
+ method chaining */
+```
 
-_Method signature:_
+**BusinessRule Definition**
 
 ```typescript
-configureConditionalRendering(
-    condition: () => boolean,
-    dependencies?: DOMNodeReference[],
-    clearValuesOnHide: boolean = true
-  ): DOMNodeReference /* Instance of this returned
-  for optional method chaining */
+interface IBusinessRule {
+  setVisibility?: [
+    condition: () => boolean, 
+    clearValuesOnHide?: boolean = true
+    ];
+  setRequired?: [
+    isRequired: () => boolean,
+    isValid: () => boolean
+  ];
+  setValue?: [
+    condition: () => boolean, 
+    value: () => any | any
+    ];
+  setDisabled?: () => boolean;
+}
 ```
 
-_Example implementation:_
+##### Visibility Control
 
 ```typescript
-node.configureConditionalRendering(
-  function () // Function to evaluate wether this node should be visible or not
+// Show the 'taxIdField' only when
+// 'businessTypeField' is set to 'Corporation' or 'LLC'
+taxIdField.applyBusinessRule(
   {
-    return otherNode.value === "some value";
+    setVisibility: [
+      () =>
+        businessTypeField.value === "Corporation" ||
+        businessTypeField.value === "LLC",
+    ],
   },
-  [otherNode] /* Dependency array | if the values or visibility of these
-  change, the function is re-evaluated */,
+  [businessTypeField] // Re-evaluate when businessTypeField changes
+);
 
-  true /* should the values in the targeted elements (this.element)
-  be cleared if this node is hidden? Default = true */
+// Optionally disable 'clearValuesOnHide:
+taxIdField.applyBusinessRule(
+  {
+    setVisibility: [
+      () =>
+        businessTypeField.value === "Corporation" ||
+        businessTypeField.value === "LLC",
+      false, // defaults to true. False will prevent the fields from losing it's value if it is hidden
+    ],
+  },
+  [businessTypeField] // Re-evaluate when businessTypeField changes
 );
 ```
 
 ##### Validation and Requirements
 
-This utility enhances PowerPages forms by adding dynamic field validation and conditional requirements based on other field values.
-
-_Method signature:_
-
 ```typescript
-configureValidationAndRequirements(
-  isRequired: () => boolean,
-  isValid: () => boolean,
-  fieldDisplayName: string,
-  dependencies: DOMNodeReference[]
-): DOMNodeReference; /* instance of this is returned for optional
- method chaining */
+// Require 'taxIdField' when 'businessTypeField' is 'Corporation' or 'LLC'
+taxIdField.applyBusinessRule(
+  {
+    setRequired: [
+      function () {
+        return (
+          businessTypeField.value === "Corporation" ||
+          businessTypeField.value === "LLC"
+        );
+      },
+      function () {
+        return this.value != null && this.value !== "";
+      },
+    ],
+  },
+  [businessTypeField] // Revalidate when businessTypeField changes
+);
 ```
 
-_Example implementation:_
+##### Setting Field Values Conditionally
 
 ```typescript
-node.configureValidationAndRequirements(
-  // Make field required only when "Yes" is checked
-  () => dependentNode.yesRadio?.checked ?? false,
-
-  // Basic validation: ensure field isn't empty
-  function () {
-    return this.value != null && this.value !== "";
+// Set default industry value when 'businessTypeField' is 'Corporation'
+industryField.applyBusinessRule(
+  {
+    setValue: [() => businessTypeField.value === "Corporation", "Corporate"],
   },
+  [businessTypeField] // Apply value when businessTypeField changes
+);
+```
 
-  "Contact Phone", // Shows in error message: "Contact Phone is required"
+##### Enabling and Disabling Fields
 
-  [dependentNode] // Revalidate when dependentNode changes
+```typescript
+// Disable 'taxIdField' when 'businessTypeField' is 'Individual'
+taxIdField.applyBusinessRule(
+  {
+    setDisabled: [() => businessTypeField.value === "Individual"],
+  },
+  [businessTypeField] // Enable/disable when businessTypeField changes
 );
 ```
 
@@ -261,7 +298,6 @@ _Enabling/Disabling inputs_
 ```typescript
 node.disable();
 node.enable();
-
 ```
 
 ##### Label and Tooltip Management
@@ -295,6 +331,89 @@ title.addTooltip("This is an Example of a tooltip!", { color: "red" });
 
 ![Example](./assets//infoIconExample.gif)
 
+Here's an improved markdown documentation with more comprehensive details:
+
+### BindForm Method
+
+The `bindForm` method simplifies form element management in DataVerse by providing a semantic and efficient way to access form controls, sections, and tabs.
+
+##### Key Features
+
+- Retrieves form definition directly from DataVerse
+- Automatically generates references for:
+  - Controls
+  - Sections
+  - Tabs
+
+##### Element Types
+
+| Element Type | Description                                 | Accessibility             |
+| ------------ | ------------------------------------------- | ------------------------- |
+| `control`    | Includes all form fields and sub-grids      | Accessed via logical name |
+| `section`    | Standard PowerApps form sections            | Accessed via logical name |
+| `tab`        | Form tabs corresponding to PowerApps layout | Accessed via logical name |
+
+##### Usage Example
+
+```javascript
+import { bindForm } from "powerpagestoolkit";
+
+// Basic form binding
+bindForm("form-guid").then((form) => {
+  // Access elements by their logical name
+  const nameField = form["name"];
+
+  // execute custom methods
+  nameField.applyBusinessRule(
+    {
+      setVisibility: [() => someNode.value === "desired value"],
+    },
+    [someNode]
+  );
+
+  // Or executes methods immediately upon accessing
+  form["phonenumber"].addTooltip("Example tooltip text");
+});
+```
+
+##### Method Signature
+
+```typescript
+/**
+ * Binds a form by its GUID and returns a collection of form elements
+ * @param formGuid Unique identifier for the form
+ * @returns Promise resolving to form element references
+ */
+function bindForm(formGuid: string): Promise<DOMNodeReferenceArray & Record<string: DOMNodeReference>>;
+```
+
+##### Benefits
+
+- Reduces code complexity
+- Improves readability
+- Provides type-safe access to form elements
+- Supports flexible form interactions
+
+##### Best Practices
+
+- Use logical names consistently
+- Handle async nature of form binding
+- Leverage TypeScript for enhanced type checking
+
+##### Error Handling
+
+Ensure proper error handling for form binding:
+
+```javascript
+bindForm("form-guid")
+  .then((form) => {
+    // Form processing
+  })
+  .catch((error) => {
+    console.error("Form binding failed", error);
+  });
+```
+
 ### DataVerse API
 
 Perform secure API calls to DataVerse from your PowerPages site. This method implements the shell deferred token to send requests with `__RequestVerificationToken`

package/dist/DOMNodeReference.d.ts

@@ -9,24 +9,21 @@ interface IBusinessRule {
     setVisibility?: [condition: () => boolean, clearValuesOnHide?: boolean];
     /**
      * @param isRequired Function determining if field is required
-     * @param isValid Function validating field input. allows access to the invoked expression passed by {@link isRequired}
+     * @param isValid Function validating field input.
      */
-    setRequired?: [
-        isRequired: () => boolean,
-        isValid: (isRequired: () => boolean) => boolean
-    ];
+    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];
+    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?: [condition: () => boolean];
+    setDisabled?: () => boolean;
 }
 export declare const _init: unique symbol;
 declare const _destroy: unique symbol;

package/dist/bundle.js

@@ -916,7 +916,7 @@ var DOMNodeReference = class _DOMNodeReference {
           evaluationfunction: () => {
             const isFieldRequired = isRequired.bind(this)();
             const isFieldVisible = window.getComputedStyle(this.visibilityController).display !== "none";
-            return !isFieldRequired || !isFieldVisible || isValid.bind(this)(isRequired.bind(this));
+            return !isFieldRequired || !isFieldVisible || isValid.bind(this)();
           }
         });
         Page_Validators.push(newValidator);
@@ -928,7 +928,8 @@ var DOMNodeReference = class _DOMNodeReference {
         );
       }
       if (rule.setValue) {
-        const [condition, value] = rule.setValue;
+        let [condition, value] = rule.setValue;
+        if (value instanceof Function) value = value();
         if (condition.bind(this)()) {
           this.setValue.bind(this)(value);
         }
@@ -945,7 +946,7 @@ var DOMNodeReference = class _DOMNodeReference {
         }
       }
       if (rule.setDisabled) {
-        const [condition] = rule.setDisabled;
+        const condition = rule.setDisabled;
         condition.bind(this)() ? this.disable() : this.enable();
         if (dependencies.length) {
           this._configDependencyTracking(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "powerpagestoolkit",
-  "version": "2.7.0",
+  "version": "2.7.001",
   "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/index.js",
   "types": "./dist/index.d.ts",