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

package/lib/mjs/utils/utils.js

@@ -46,65 +46,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.
  */
-export function evaluate(func, args, ret, tokenize) {
-    let returnVal = null;
-    const component = args.component ? args.component : { key: 'unknown' };
-    if (!args.form && args.instance) {
-        args.form = _.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 _.get(args.data, $2.replace('data.', ''));
-                }
-                else if ($2.indexOf('row.') === 0) {
-                    return _.get(args.row, $2.replace('row.', ''));
-                }
-                // Support legacy...
-                return _.get(args.data, $2);
-            });
-        }
-        try {
-            func = Evaluator.evaluator(func, args);
-            args = _.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.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 = jsonLogic.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;
+export function evaluate(func, args, ret, interpolate, options = {}) {
+    return Evaluator.evaluate(func, args, ret, interpolate, undefined, options);
 }
 /**
  * Returns a random compoennt ID.
@@ -1021,9 +968,9 @@ export function iterateKey(key) {
 }
 /**
  * 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.
  */
 export function uniqueKey(map, base) {
     let newKey = base;
@@ -1034,8 +981,9 @@ export function uniqueKey(map, base) {
 }
 /**
  * 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.
  */
 export function bootstrapVersion(options) {
     if (options.bootstrap) {
@@ -1052,9 +1000,8 @@ export function bootstrapVersion(options) {
 /**
  * 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.
  */
 export function unfold(e) {
     if (typeof e === 'function') {
@@ -1064,36 +1011,31 @@ export function unfold(e) {
 }
 /**
  * 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.
  */
 export const firstNonNil = _.flow([
     _.partialRight(_.map, unfold),
     _.partialRight(_.find, v => !_.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];
  */
 export 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;
@@ -1103,9 +1045,12 @@ export function withSwitch(a, b) {
     return [get, toggle];
 }
 /**
- *
- * @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.
  */
 export function observeOverload(callback, options = {}) {
     const { limit = 50, delay = 500 } = options;
@@ -1127,12 +1072,13 @@ export function observeOverload(callback, options = {}) {
     };
 }
 /**
- *
- * @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.
  */
-export function getContextComponents(context, excludeNested = false, excludedTypes = []) {
+export function getContextComponents(context, excludeNested, excludedTypes = []) {
     const values = [];
     context.utils.eachComponent(context.instance.options.editForm.components, (component, path) => {
         const addToContextComponents = excludeNested ? !component.tree : true;
@@ -1146,8 +1092,9 @@ export function getContextComponents(context, excludeNested = false, excludedTyp
     return values;
 }
 /**
- *
- * @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.
  */
 export function getContextButtons(context) {
     const values = [];
@@ -1165,10 +1112,9 @@ export function getContextButtons(context) {
 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) {
@@ -1199,8 +1145,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) {
@@ -1216,10 +1162,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.
  */
 export function translateHTMLTemplate(template, translate) {
     const isHTML = /<[^>]*>/.test(template);
@@ -1236,9 +1181,9 @@ export function translateHTMLTemplate(template, translate) {
 }
 /**
  * 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.
  */
 export function sanitize(string, options) {
     if (typeof dompurify.sanitize !== 'function') {
@@ -1286,15 +1231,17 @@ export function sanitize(string, options) {
 }
 /**
  * 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.
  */
 export function fastCloneDeep(obj) {
     return obj ? JSON.parse(JSON.stringify(obj)) : obj;
 }
 export { Evaluator, interpolate };
 /**
- *
- * @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.
  */
 export function isInputComponent(componentJson) {
     if (componentJson.input === false || componentJson.input === true) {
@@ -1316,8 +1263,9 @@ export function isInputComponent(componentJson) {
     }
 }
 /**
- *
- * @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.
  */
 export function getArrayFromComponentPath(pathStr) {
     if (!pathStr || !_.isString(pathStr)) {
@@ -1333,9 +1281,10 @@ export function getArrayFromComponentPath(pathStr) {
         .map(part => _.defaultTo(_.toNumber(part), part));
 }
 /**
- *
- * @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.
  */
 export function isChildOf(child, parent) {
     while (child && child.parent) {
@@ -1347,8 +1296,9 @@ export function isChildOf(child, parent) {
     return false;
 }
 /**
- *
- * @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.
  */
 export function getStringFromComponentPath(path) {
     if (!_.isArray(path)) {
@@ -1366,19 +1316,20 @@ export function getStringFromComponentPath(path) {
     return strPath;
 }
 /**
- *
- * @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.
  */
 export function round(number, precision) {
     if (_.isNumber(number)) {
         return number.toFixed(precision);
     }
-    return number;
+    return number.toString();
 }
 /**
  * Check for Internet Explorer browser version
- * @returns {(number|null)}
+ * @returns {(number|null)} - The IE browser version or null if not IE
  */
 export function getIEBrowserVersion() {
     const { ie, version } = getBrowserInfo();
@@ -1435,16 +1386,18 @@ export function getBrowserInfo() {
     return browser;
 }
 /**
- *
- * @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.
  */
 export function getComponentPathWithoutIndicies(path = '') {
     return path.replace(/\[\d+\]/, '');
 }
 /**
  * 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
  */
 export function getComponentPath(component, path = '') {
     if (!component || !component.key || component?._form?.display === 'wizard') { // unlike the Webform, the Wizard has the key and it is a duplicate of the panel key
@@ -1455,8 +1408,8 @@ export function getComponentPath(component, path = '') {
 }
 /**
  * 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.
  */
 export function getDataParentComponent(componentInstance) {
     if (!componentInstance) {
@@ -1472,8 +1425,8 @@ export function getDataParentComponent(componentInstance) {
 }
 /**
  * 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
  */
 export function isPromise(value) {
     return value
@@ -1484,9 +1437,9 @@ export function isPromise(value) {
 /**
  * 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
  */
 export function isInsideScopingComponent(componentInstance, firstPass = true) {
     if (!firstPass && componentInstance?.hasScopedChildren) {
@@ -1502,8 +1455,9 @@ export function isInsideScopingComponent(componentInstance, firstPass = true) {
     return false;
 }
 /**
- *
- * @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.
  */
 export function getFocusableElements(element) {
     const focusableSelector = `button:not([disabled]), input:not([disabled]), select:not([disabled]),
@@ -1522,8 +1476,9 @@ export const 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
  */
 export function getComponentSavedTypes(fullSchema) {
     const schema = fullSchema || {};
@@ -1537,11 +1492,10 @@ export function getComponentSavedTypes(fullSchema) {
 }
 /**
  * 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
  */
 export const interpolateErrors = (component, errors, interpolateFn) => {
     return errors.map((error) => {
@@ -1552,8 +1506,9 @@ export const interpolateErrors = (component, errors, interpolateFn) => {
     });
 };
 /**
- *
- * @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.
  */
 export function getItemTemplateKeys(template) {
     const templateKeys = [];
@@ -1572,8 +1527,9 @@ export function getItemTemplateKeys(template) {
     return templateKeys;
 }
 /**
- *
- * @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.
  */
 export function isSelectResourceWithObjectValue(comp = {}) {
     const { reference, dataSrc, valueProperty } = comp;

package/lib/mjs/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/mjs/widgets/CalendarWidget.js

@@ -246,11 +246,11 @@ export default class CalendarWidget extends InputWidget {
         return _.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) {
@@ -260,7 +260,7 @@ export default class CalendarWidget extends InputWidget {
     }
     /**
      * Return the value of the selected date.
-     * @returns {*}
+     * @returns {*} - The value of the selected date.
      */
     getValue() {
         // Standard output format.
@@ -282,7 +282,8 @@ export default class CalendarWidget extends InputWidget {
     }
     /**
      * Set the selected date value.
-     * @param value
+     * @param {*} value - The value to set.
+     * @returns {void}
      */
     setValue(value) {
         const saveAsText = (this.settings.saveAs === 'text');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formio/js",
-  "version": "5.0.0-rc.54",
+  "version": "5.0.0-rc.56",
   "description": "JavaScript powered Forms with JSON Form Builder",
   "main": "lib/cjs/index.js",
   "exports": {
@@ -38,8 +38,8 @@
     "lint"
   ],
   "scripts": {
-    "build": "yarn lib && yarn dist",
-    "doc": "",
+    "build": "yarn doc && yarn lib && yarn dist",
+    "doc": "typedoc",
     "dist": "gulp clean:dist && webpack --config webpack.config.js && webpack --config webpack.prod.js && gulp build",
     "lib": "gulp clean:lib && tsc --project tsconfig.cjs.json && tsc --project tsconfig.mjs.json && yarn lib:package",
     "lib:package": "node ./libpackage.js",
@@ -81,7 +81,7 @@
   "dependencies": {
     "@formio/bootstrap": "^3.0.0-rc.24",
     "@formio/choices.js": "^10.2.1",
-    "@formio/core": "^2.1.0-dev.tt.8",
+    "@formio/core": "^2.1.0-dev.tt.12",
     "@formio/text-mask-addons": "^3.8.0-formio.2",
     "@formio/vanilla-text-mask": "^5.1.1-formio.1",
     "abortcontroller-polyfill": "^1.7.5",
@@ -128,8 +128,6 @@
     "chance": "^1.1.9",
     "ejs-loader": "^0.5.0",
     "escape-string-regexp": "^5.0.0",
-    "esdoc-ecmascript-proposal-plugin": "^1.0.0",
-    "esdoc-standard-plugin": "^1.0.0",
     "eslint": "^8.57.0",
     "eslint-plugin-jsdoc": "^48.2.5",
     "fetch-mock": "^9.11.0",
@@ -176,7 +174,6 @@
     "webpack-bundle-analyzer": "^4.10.2",
     "webpack-cli": "^5.1.1",
     "webpack-node-externals": "^3.0.0",
-    "webpack-stream": "^7.0.0",
-    "written-number": "^0.11.1"
+    "webpack-stream": "^7.0.0"
   }
 }