@formio/js 5.0.0-rc.54 → 5.0.0-rc.55

package/lib/cjs/utils/utils.js

@@ -83,65 +83,12 @@ function setPathToComponentAndPerentSchema(component) {
  * @param {Function|string|object} func - The function to evaluate.
  * @param {*} args - A map of arguments to pass to the function.
  * @param {string} ret - The name of the "return" variable in the script.
- * @param {boolean} tokenize - True if the script should be interpolated before being executed.
+ * @param {boolean} interpolate - True if the script should be interpolated before being executed.
+ * @param {import('@formio/core').EvaluatorOptions} options - The evaluator options.
  * @returns {*} - The result of the evaluation.
  */
-function evaluate(func, args, ret, tokenize) {
-    let returnVal = null;
-    const component = args.component ? args.component : { key: 'unknown' };
-    if (!args.form && args.instance) {
-        args.form = lodash_1.default.get(args.instance, 'root._form', {});
-    }
-    const componentKey = component.key;
-    if (typeof func === 'string') {
-        if (ret) {
-            func += `;return ${ret}`;
-        }
-        if (tokenize) {
-            // Replace all {{ }} references with actual data.
-            func = func.replace(/({{\s+(.*)\s+}})/, (match, $1, $2) => {
-                if ($2.indexOf('data.') === 0) {
-                    return lodash_1.default.get(args.data, $2.replace('data.', ''));
-                }
-                else if ($2.indexOf('row.') === 0) {
-                    return lodash_1.default.get(args.row, $2.replace('row.', ''));
-                }
-                // Support legacy...
-                return lodash_1.default.get(args.data, $2);
-            });
-        }
-        try {
-            func = Evaluator_1.Evaluator.evaluator(func, args);
-            args = lodash_1.default.values(args);
-        }
-        catch (err) {
-            console.warn(`An error occured within the custom function for ${componentKey}`, err);
-            returnVal = null;
-            func = false;
-        }
-    }
-    if (typeof func === 'function') {
-        try {
-            returnVal = Evaluator_1.Evaluator.evaluate(func, args);
-        }
-        catch (err) {
-            returnVal = null;
-            console.warn(`An error occured within custom function for ${componentKey}`, err);
-        }
-    }
-    else if (typeof func === 'object') {
-        try {
-            returnVal = json_logic_js_1.default.apply(func, args);
-        }
-        catch (err) {
-            returnVal = null;
-            console.warn(`An error occured within custom function for ${componentKey}`, err);
-        }
-    }
-    else if (func) {
-        console.warn(`Unknown function type for ${componentKey}`);
-    }
-    return returnVal;
+function evaluate(func, args, ret, interpolate, options = {}) {
+    return Evaluator_1.Evaluator.evaluate(func, args, ret, interpolate, undefined, options);
 }
 exports.evaluate = evaluate;
 /**
@@ -1100,9 +1047,9 @@ function iterateKey(key) {
 exports.iterateKey = iterateKey;
 /**
  * Determines a unique key within a map provided the base key.
- * @param map
- * @param base
- * @returns {*}
+ * @param {Record<string, string>} map - The map to check for uniqueness.
+ * @param {string} base - The base path of the key.
+ * @returns {string} - The unique key.
  */
 function uniqueKey(map, base) {
     let newKey = base;
@@ -1114,8 +1061,9 @@ function uniqueKey(map, base) {
 exports.uniqueKey = uniqueKey;
 /**
  * Determines the major version number of bootstrap.
- * @param options
- * @returns {number}
+ * @param {object} options - The options to check for bootstrap version.
+ * @param {string} options.bootstrap - The bootstrap version to use.
+ * @returns {number} - The bootstrap version.
  */
 function bootstrapVersion(options) {
     if (options.bootstrap) {
@@ -1133,9 +1081,8 @@ exports.bootstrapVersion = bootstrapVersion;
 /**
  * Retrun provided argument.
  * If argument is a function, returns the result of a function call.
- * @param {*} e;
- * @param e
- * @returns {*}
+ * @param {Function|any} e - The argument to check if a function and call if so.
+ * @returns {any} - Either the result of the function call (e) or e if it is not a function.
  */
 function unfold(e) {
     if (typeof e === 'function') {
@@ -1146,36 +1093,31 @@ function unfold(e) {
 exports.unfold = unfold;
 /**
  * Map values through unfold and return first non-nil value.
- * @param {Array<T>} collection;
- * @returns {T}
+ * @param {Array<T>} collection - The collection to map through unfold.;
+ * @returns {T} - The first non-nil value.
  */
 exports.firstNonNil = lodash_1.default.flow([
     lodash_1.default.partialRight(lodash_1.default.map, unfold),
     lodash_1.default.partialRight(lodash_1.default.find, v => !lodash_1.default.isUndefined(v))
 ]);
-/*
- * Create enclosed state.
- * Returns functions to getting and cycling between states.
+/**
+ * Create enclosed state. Returns functions to getting and cycling between states.
  * @param {*} a - initial state.
  * @param {*} b - next state.
- * @return {Functions[]} -- [get, toggle];
- */
-/**
- *
- * @param a
- * @param b
+ * @returns {Functions[]} -- [get, toggle];
  */
 function withSwitch(a, b) {
     let state = a;
     let next = b;
     /**
-     *
+     * Returns the state of the switch.
+     * @returns {*} - The current state.
      */
     function get() {
         return state;
     }
     /**
-     *
+     * Toggles the state of the switch.
      */
     function toggle() {
         const prev = state;
@@ -1186,9 +1128,12 @@ function withSwitch(a, b) {
 }
 exports.withSwitch = withSwitch;
 /**
- *
- * @param callback
- * @param options
+ * Create a function that will call the provided function only the provided limit.
+ * @param {Function} callback - The callback to call.
+ * @param {object} options - The options to use.
+ * @param {number} options.limit - The limit to call the callback.
+ * @param {number} options.delay - The delay to wait before resetting the call count.
+ * @returns {Function} - The function that will call the callback only the provided limit.
  */
 function observeOverload(callback, options = {}) {
     const { limit = 50, delay = 500 } = options;
@@ -1211,12 +1156,13 @@ function observeOverload(callback, options = {}) {
 }
 exports.observeOverload = observeOverload;
 /**
- *
- * @param context
- * @param excludeNested
- * @param excludedTypes
+ * Returns the components that are provided within an evaluation context.
+ * @param {any} context - The evaluation context to get the components from.
+ * @param {boolean} excludeNested - Exclude nested components.
+ * @param {Array<string>} excludedTypes - The types of components to exclude.
+ * @returns {Array} - The components within the evaluation context.
  */
-function getContextComponents(context, excludeNested = false, excludedTypes = []) {
+function getContextComponents(context, excludeNested, excludedTypes = []) {
     const values = [];
     context.utils.eachComponent(context.instance.options.editForm.components, (component, path) => {
         const addToContextComponents = excludeNested ? !component.tree : true;
@@ -1231,8 +1177,9 @@ function getContextComponents(context, excludeNested = false, excludedTypes = []
 }
 exports.getContextComponents = getContextComponents;
 /**
- *
- * @param context
+ * Returns the button components that are within an evaluation context.
+ * @param {any} context - The evaluation context to get the components from.
+ * @returns {Array} - The button components within the evaluation context.
  */
 function getContextButtons(context) {
     const values = [];
@@ -1251,10 +1198,9 @@ exports.getContextButtons = getContextButtons;
 const inTextTags = ['#text', 'A', 'B', 'EM', 'I', 'SMALL', 'STRONG', 'SUB', 'SUP', 'INS', 'DEL', 'MARK', 'CODE'];
 /**
  * Helper function for 'translateHTMLTemplate'. Translates text value of the passed html element.
- * @param {HTMLElement} elem
- * @param {Function} translate
- * @returns {string}
- *   Translated element template.
+ * @param {HTMLElement} elem - The element to translate.
+ * @param {Function} translate - The translation function.
+ * @returns {string} - Translated element template.
  */
 function translateElemValue(elem, translate) {
     if (!elem.innerText) {
@@ -1285,8 +1231,8 @@ function translateElemValue(elem, translate) {
 }
 /**
  * Helper function for 'translateHTMLTemplate'. Goes deep through html tag children and calls function to translate their text values.
- * @param {HTMLElement} tag
- * @param {Function} translate
+ * @param {HTMLElement} tag - The tag to translate.
+ * @param {Function} translate - The translation function.
  * @returns {void}
  */
 function translateDeepTag(tag, translate) {
@@ -1302,10 +1248,9 @@ function translateDeepTag(tag, translate) {
 }
 /**
  * Translates text values in html template.
- * @param {string} template
- * @param {Function} translate
- * @returns {string}
- *   Html template with translated values.
+ * @param {string} template - The template to translate.
+ * @param {Function} translate - The translation function.
+ * @returns {string} - Html template with translated values.
  */
 function translateHTMLTemplate(template, translate) {
     const isHTML = /<[^>]*>/.test(template);
@@ -1323,9 +1268,9 @@ function translateHTMLTemplate(template, translate) {
 exports.translateHTMLTemplate = translateHTMLTemplate;
 /**
  * Sanitize an html string.
- * @param string
- * @param options
- * @returns {*}
+ * @param {string} string - The string to sanitize.
+ * @param {any} options - The options to use for sanitization.
+ * @returns {string} - The sanitized html string.
  */
 function sanitize(string, options) {
     if (typeof dompurify_1.default.sanitize !== 'function') {
@@ -1374,15 +1319,17 @@ function sanitize(string, options) {
 exports.sanitize = sanitize;
 /**
  * Fast cloneDeep for JSON objects only.
- * @param obj
+ * @param {any} obj - The object to perform a fast clone deep against.
+ * @returns {any} - The cloned object.
  */
 function fastCloneDeep(obj) {
     return obj ? JSON.parse(JSON.stringify(obj)) : obj;
 }
 exports.fastCloneDeep = fastCloneDeep;
 /**
- *
- * @param componentJson
+ * Returns if the component is an input component.
+ * @param {import('@formio/core').Component} componentJson - The JSON of a component.
+ * @returns {bool} - TRUE if the component is an input component; FALSE otherwise.
  */
 function isInputComponent(componentJson) {
     if (componentJson.input === false || componentJson.input === true) {
@@ -1405,8 +1352,9 @@ function isInputComponent(componentJson) {
 }
 exports.isInputComponent = isInputComponent;
 /**
- *
- * @param pathStr
+ * Takes a component path, and returns a component path array.
+ * @param {string} pathStr - The path string to convert to an array.
+ * @returns {Arryay<number>} - The array of paths.
  */
 function getArrayFromComponentPath(pathStr) {
     if (!pathStr || !lodash_1.default.isString(pathStr)) {
@@ -1423,9 +1371,10 @@ function getArrayFromComponentPath(pathStr) {
 }
 exports.getArrayFromComponentPath = getArrayFromComponentPath;
 /**
- *
- * @param child
- * @param parent
+ * Returns true if the component is a child of the parent.
+ * @param {any} child - The child component to check.
+ * @param {any} parent - The parent component to check.
+ * @returns {boolean} - TRUE if the child is a child of the parent; FALSE otherwise.
  */
 function isChildOf(child, parent) {
     while (child && child.parent) {
@@ -1438,8 +1387,9 @@ function isChildOf(child, parent) {
 }
 exports.isChildOf = isChildOf;
 /**
- *
- * @param path
+ * Takes an array of component path indexes, and returns a string version of that array.
+ * @param {Array<number>} path - The path array to convert to a string.
+ * @returns {string} - The string version of the path.
  */
 function getStringFromComponentPath(path) {
     if (!lodash_1.default.isArray(path)) {
@@ -1458,20 +1408,21 @@ function getStringFromComponentPath(path) {
 }
 exports.getStringFromComponentPath = getStringFromComponentPath;
 /**
- *
- * @param number
- * @param precision
+ * Takes a number and rounds it to the provided precision amount.
+ * @param {number} number - The number to round.
+ * @param {number} precision - The precision to round the number to.
+ * @returns {string} - The rounded number.
  */
 function round(number, precision) {
     if (lodash_1.default.isNumber(number)) {
         return number.toFixed(precision);
     }
-    return number;
+    return number.toString();
 }
 exports.round = round;
 /**
  * Check for Internet Explorer browser version
- * @returns {(number|null)}
+ * @returns {(number|null)} - The IE browser version or null if not IE
  */
 function getIEBrowserVersion() {
     const { ie, version } = getBrowserInfo();
@@ -1530,8 +1481,9 @@ function getBrowserInfo() {
 }
 exports.getBrowserInfo = getBrowserInfo;
 /**
- *
- * @param path
+ * Takes a component path, which may include array indicies (i.e. [0][1]), and returns the compoennt path without the indicies.
+ * @param {string} path - The path to remove the indicies from.
+ * @returns {string} - The path without the indicies.
  */
 function getComponentPathWithoutIndicies(path = '') {
     return path.replace(/\[\d+\]/, '');
@@ -1539,8 +1491,9 @@ function getComponentPathWithoutIndicies(path = '') {
 exports.getComponentPathWithoutIndicies = getComponentPathWithoutIndicies;
 /**
  * Returns a path to the component which based on its schema
- * @param {*} component is a component's schema containing link to its parent's schema in the 'parent' property
- * @param path
+ * @param {import('@formio/core').Component} component - Component containing link to its parent's schema in the 'parent' property
+ * @param {string} path - Path to the component
+ * @returns {string} - Path to the component
  */
 function getComponentPath(component, path = '') {
     var _a;
@@ -1553,8 +1506,8 @@ function getComponentPath(component, path = '') {
 exports.getComponentPath = getComponentPath;
 /**
  * Returns a parent component of the passed component instance skipping all the Layout components
- * @param {*} componentInstance
- * @returns {(Component|undefined)}
+ * @param {Component} componentInstance - The component to check for the parent.
+ * @returns {Component|undefined} - The parent data component.
  */
 function getDataParentComponent(componentInstance) {
     if (!componentInstance) {
@@ -1571,8 +1524,8 @@ function getDataParentComponent(componentInstance) {
 exports.getDataParentComponent = getDataParentComponent;
 /**
  * Returns whether the value is a promise
- * @param value
- * @returns {boolean}
+ * @param {any} value - The value to check
+ * @returns {boolean} - TRUE if the value is a promise; FALSE otherwise
  */
 function isPromise(value) {
     return value
@@ -1584,9 +1537,9 @@ exports.isPromise = isPromise;
 /**
  * Determines if the component has a scoping parent in tree (a component which scopes its children and manages its
  * changes by itself, e.g. EditGrid)
- * @param componentInstance
- * @param firstPass
- * @returns {boolean|boolean|*}
+ * @param {Component} componentInstance - The component to check for the scoping parent.
+ * @param {boolean} firstPass - Whether it is the first pass of the function
+ * @returns {boolean|*} - TRUE if the component has a scoping parent; FALSE otherwise
  */
 function isInsideScopingComponent(componentInstance, firstPass = true) {
     if (!firstPass && (componentInstance === null || componentInstance === void 0 ? void 0 : componentInstance.hasScopedChildren)) {
@@ -1603,8 +1556,9 @@ function isInsideScopingComponent(componentInstance, firstPass = true) {
 }
 exports.isInsideScopingComponent = isInsideScopingComponent;
 /**
- *
- * @param element
+ * Returns all the focusable elements within the provided dom element.
+ * @param {HTMLElement} element - The element to get the focusable elements from.
+ * @returns {NodeList<HTMLElement>} - The focusable elements within the provided element.
  */
 function getFocusableElements(element) {
     const focusableSelector = `button:not([disabled]), input:not([disabled]), select:not([disabled]),
@@ -1622,8 +1576,9 @@ exports.componentValueTypes = {
     any: 'any',
 };
 /**
- *
- * @param fullSchema
+ * Returns the saved types for the component
+ * @param {import('@formio/core').Component} fullSchema - The component schema
+ * @returns {Array<string>|null} - The saved types for the component
  */
 function getComponentSavedTypes(fullSchema) {
     const schema = fullSchema || {};
@@ -1638,11 +1593,10 @@ function getComponentSavedTypes(fullSchema) {
 exports.getComponentSavedTypes = getComponentSavedTypes;
 /**
  * Interpolates @formio/core errors so that they are compatible with the renderer
- * @param component
- * @param {FieldError[]} errors
- * @param firstPass
- * @param interpolateFn
- * @returns {[]}
+ * @param {Component} component - The component to interpolate the errors for
+ * @param {FieldError[]} errors - The errors to interpolate
+ * @param {Function} interpolateFn - The interpolation function
+ * @returns {[]} - The interpolated errors
  */
 const interpolateErrors = (component, errors, interpolateFn) => {
     return errors.map((error) => {
@@ -1654,8 +1608,9 @@ const interpolateErrors = (component, errors, interpolateFn) => {
 };
 exports.interpolateErrors = interpolateErrors;
 /**
- *
- * @param template
+ * Returns the template keys inside the template code.
+ * @param {string} template - The template to get the keys from.
+ * @returns {Array<string>} - The keys inside the template.
  */
 function getItemTemplateKeys(template) {
     const templateKeys = [];
@@ -1675,8 +1630,9 @@ function getItemTemplateKeys(template) {
 }
 exports.getItemTemplateKeys = getItemTemplateKeys;
 /**
- *
- * @param comp
+ * Returns if the component is a select resource with an object for its value.
+ * @param {import('@formio/core').Component} comp - The component to check.
+ * @returns {boolean} - TRUE if the component is a select resource with an object for its value; FALSE otherwise.
  */
 function isSelectResourceWithObjectValue(comp = {}) {
     const { reference, dataSrc, valueProperty } = comp;

package/lib/cjs/widgets/CalendarWidget.d.ts

@@ -70,17 +70,18 @@ export default class CalendarWidget extends InputWidget {
     get dateTimeFormat(): string;
     get dateFormat(): any;
     /**
-     * Return the date value.
-     * @param date
-     * @param format
-     * @param useTimezone
-     * @returns {string}
+     * Return the date value as a string.
+     * @param {string|Date} date - The date object or a date string that is momentjs compatible.
+     * @param {string} format - The DateParser code format.
+     * @param {boolean} [useTimezone] - If the timezone should be used.
+     * @returns {string} - Returns the formatted date string.
      */
-    getDateValue(date: any, format: any, useTimezone: any): string;
+    getDateValue(date: string | Date, format: string, useTimezone?: boolean | undefined): string;
     isValueISO8601(value: any): any;
     /**
      * Set the selected date value.
-     * @param value
+     * @param {*} value - The value to set.
+     * @returns {void}
      */
     setValue(value: any): void;
     getValueAsString(value: any, format: any): string;

package/lib/cjs/widgets/CalendarWidget.js

@@ -254,11 +254,11 @@ class CalendarWidget extends InputWidget_1.default {
         return lodash_1.default.get(this.settings, 'format', DEFAULT_FORMAT);
     }
     /**
-     * Return the date value.
-     * @param date
-     * @param format
-     * @param useTimezone
-     * @returns {string}
+     * Return the date value as a string.
+     * @param {string|Date} date - The date object or a date string that is momentjs compatible.
+     * @param {string} format - The DateParser code format.
+     * @param {boolean} [useTimezone] - If the timezone should be used.
+     * @returns {string} - Returns the formatted date string.
      */
     getDateValue(date, format, useTimezone) {
         if (useTimezone) {
@@ -268,7 +268,7 @@ class CalendarWidget extends InputWidget_1.default {
     }
     /**
      * Return the value of the selected date.
-     * @returns {*}
+     * @returns {*} - The value of the selected date.
      */
     getValue() {
         // Standard output format.
@@ -290,7 +290,8 @@ class CalendarWidget extends InputWidget_1.default {
     }
     /**
      * Set the selected date value.
-     * @param value
+     * @param {*} value - The value to set.
+     * @returns {void}
      */
     setValue(value) {
         const saveAsText = (this.settings.saveAs === 'text');

package/lib/mjs/Element.d.ts

@@ -233,10 +233,11 @@ export default class Element {
      * @param {string|Function|object} func - The function or string to evaluate.
      * @param {object} args - The arguments to pass to the evaluation.
      * @param {string} ret - The name of the variable within the evaluation context to return.
-     * @param {boolean} tokenize - Determines if it should replace all {{ }} token references with actual data.
+     * @param {boolean} interpolate - Determines if it should replace all {{ }} token references with actual data.
+     * @param {import('@formio/core').EvaluatorOptions} options - The options to pass to the evaluation.
      * @returns {*} - The result of the evaluation.
      */
-    evaluate(func: string | Function | object, args: object, ret: string, tokenize: boolean): any;
+    evaluate(func: string | Function | object, args: object, ret: string, interpolate: boolean, options?: import('@formio/core').EvaluatorOptions): any;
     /**
      * Allow for options to hook into the functionality of this renderer.
      * @returns {*} - The result of the hook function.

package/lib/mjs/Element.js

@@ -532,11 +532,12 @@ export default class Element {
      * @param {string|Function|object} func - The function or string to evaluate.
      * @param {object} args - The arguments to pass to the evaluation.
      * @param {string} ret - The name of the variable within the evaluation context to return.
-     * @param {boolean} tokenize - Determines if it should replace all {{ }} token references with actual data.
+     * @param {boolean} interpolate - Determines if it should replace all {{ }} token references with actual data.
+     * @param {import('@formio/core').EvaluatorOptions} options - The options to pass to the evaluation.
      * @returns {*} - The result of the evaluation.
      */
-    evaluate(func, args, ret, tokenize) {
-        return FormioUtils.evaluate(func, this.evalContext(args), ret, tokenize);
+    evaluate(func, args, ret, interpolate, options = {}) {
+        return FormioUtils.evaluate(func, this.evalContext(args), ret, interpolate, options);
     }
     /**
      * Allow for options to hook into the functionality of this renderer.