From d0b5e7e2375f0b5781f2e6544ddbe48ec586904a Mon Sep 17 00:00:00 2001 From: Brendan Bond Date: Tue, 23 Apr 2024 11:32:39 -0500 Subject: [PATCH] FIO-7733: update webform types; export webform; (#5516) * update webform types; export eventemitter and webform; * minor typo * type options --- src/Webform.js | 122 +++++++++++++++--- .../_classes/nested/NestedComponent.js | 7 +- src/formio.form.js | 3 +- 3 files changed, 112 insertions(+), 20 deletions(-) diff --git a/src/Webform.js b/src/Webform.js index 1c26e0f962..48de614951 100644 --- a/src/Webform.js +++ b/src/Webform.js @@ -1,7 +1,7 @@ import _ from 'lodash'; import moment from 'moment'; import { compareVersions } from 'compare-versions'; - +import { Component } from '@formio/core'; import EventEmitter from './EventEmitter'; import i18nDefaults from './i18n'; import { Formio } from './Formio'; @@ -15,7 +15,6 @@ import { searchComponents, convertStringToHTMLElement, getArrayFromComponentPath, - interpolateErrors } from './utils/utils'; import { eachComponent } from './utils/formUtils'; @@ -49,32 +48,121 @@ function getOptions(options) { return options; } +/** + * Represents a JSON value. + * @typedef {(string | number | boolean | null | JSONArray | JSONObject)} JSON + */ + +/** + * Represents a JSON array. + * @typedef {Array} JSONArray + */ + +/** + * Represents a JSON object. + * @typedef {{[key: string]: JSON}} JSONObject + */ + +/** + * @typedef {Object} FormioHooks + * @property {function} [beforeSubmit] + * @property {function} [beforeCancel] + * @property {function} [beforeNext] + * @property {function} [beforePrev] + * @property {function} [attachComponent] + * @property {function} [setDataValue] + * @property {function} [addComponents] + * @property {function} [addComponent] + * @property {function} [customValidation] + * @property {function} [attachWebform] + */ + +/** + * @typedef {Object} SanitizeConfig + * @property {string[]} [addAttr] + * @property {string[]} [addTags] + * @property {string[]} [allowedAttrs] + * @property {string[]} [allowedTags] + * @property {string[]} [allowedUriRegex] + * @property {string[]} [addUriSafeAttr] + */ + +/** + * @typedef {Object} ButtonSettings + * @property {boolean} [showPrevious] + * @property {boolean} [showNext] + * @property {boolean} [showCancel] + * @property {boolean} [showSubmit] + */ + +/** + * @typedef {Object} FormOptions + * @property {boolean} [saveDraft] - Enable the save draft feature. + * @property {number} [saveDraftThrottle] - The throttle for the save draft feature. + * @property {boolean} [readOnly] - Set this form to readOnly. + * @property {boolean} [noAlerts] - Disable the alerts dialog. + * @property {{[key: string]: string}} [i18n] - The translation file for this rendering. + * @property {string} [template] - Custom logic for creation of elements. + * @property {boolean} [noDefaults] - Exclude default values from the settings. + * @property {any} [fileService] - The file service for this form. + * @property {EventEmitter} [events] - The EventEmitter for this form. + * @property {string} [language] - The language to render this form in. + * @property {{[key: string]: string}} [i18next] - The i18next configuration for this form. + * @property {boolean} [viewAsHtml] - View the form as raw HTML. + * @property {'form' | 'html' | 'flat' | 'builder' | 'pdf'} [renderMode] - The render mode for this form. + * @property {boolean} [highlightErrors] - Highlight any errors on the form. + * @property {string} [componentErrorClass] - The error class for components. + * @property {any} [templates] - The templates for this form. + * @property {string} [iconset] - The iconset for this form. + * @property {Component[]} [components] - The components for this form. + * @property {{[key: string]: boolean}} [disabled] - Disabled components for this form. + * @property {boolean} [showHiddenFields] - Show hidden fields. + * @property {{[key: string]: boolean}} [hide] - Hidden components for this form. + * @property {{[key: string]: boolean}} [show] - Components to show for this form. + * @property {Formio} [formio] - The Formio instance for this form. + * @property {string} [decimalSeparator] - The decimal separator for this form. + * @property {string} [thousandsSeparator] - The thousands separator for this form. + * @property {FormioHooks} [hooks] - The hooks for this form. + * @property {boolean} [alwaysDirty] - Always be dirty. + * @property {boolean} [skipDraftRestore] - Skip restoring a draft. + * @property {'form' | 'wizard' | 'pdf'} [display] - The display for this form. + * @property {string} [cdnUrl] - The CDN url for this form. + * @property {boolean} [flatten] - Flatten the form. + * @property {boolean} [sanitize] - Sanitize the form. + * @property {SanitizeConfig} [sanitizeConfig] - The sanitize configuration for this form. + * @property {ButtonSettings} [buttonSettings] - The button settings for this form. + * @property {Object} [breadCrumbSettings] - The breadcrumb settings for this form. + * @property {boolean} [allowPrevious] - Allow the previous button (for Wizard forms). + * @property {string[]} [wizardButtonOrder] - The order of the buttons (for Wizard forms). + * @property {boolean} [showCheckboxBackground] - Show the checkbox background. + * @property {number} [zoom] - The zoom for PDF forms. + */ + /** * Renders a Form.io form within the webpage. */ export default class Webform extends NestedDataComponent { + /** + * @type {FormOptions} - the options for this Webform. + */ + options; + /** * Creates a new Form instance. * - * @param {Object} options - The options to create a new form instance. - * @param {boolean} options.saveDraft - Set this if you would like to enable the save draft feature. - * @param {boolean} options.saveDraftThrottle - The throttle for the save draft feature. - * @param {boolean} options.readOnly - Set this form to readOnly - * @param {boolean} options.noAlerts - Set to true to disable the alerts dialog. - * @param {boolean} options.i18n - The translation file for this rendering. @see https://github.com/formio/formio.js/blob/master/i18n.js - * @param {boolean} options.template - Provides a way to inject custom logic into the creation of every element rendered within the form. + * @param {HTMLElement | Object | FormOptions} [elementOrOptions] - The DOM element to render this form within or the options to create this form instance. + * @param {FormOptions} [options] - The options to create a new form instance. */ - /* eslint-disable max-statements */ - constructor() { - let element, options; - if (arguments[0] instanceof HTMLElement || arguments[1]) { - element = arguments[0]; - options = arguments[1]; + constructor(elementOrOptions, options) { + let element, formOptions; + if (elementOrOptions instanceof HTMLElement || options) { + element = elementOrOptions; + formOptions = options; } else { - options = arguments[0]; + formOptions = elementOrOptions; } - super(null, getOptions(options)); + super(null, getOptions(formOptions)); this.setElement(element); diff --git a/src/components/_classes/nested/NestedComponent.js b/src/components/_classes/nested/NestedComponent.js index 85f68a0186..188d367274 100644 --- a/src/components/_classes/nested/NestedComponent.js +++ b/src/components/_classes/nested/NestedComponent.js @@ -3,7 +3,9 @@ import _ from 'lodash'; import Field from '../field/Field'; import Components from '../../Components'; import { getArrayFromComponentPath, getStringFromComponentPath, getRandomComponentId } from '../../../utils/utils'; +import Component from '../component/Component'; import { process as processAsync, processSync } from '@formio/core/process'; + export default class NestedComponent extends Field { static schema(...extend) { return Field.schema({ @@ -218,8 +220,9 @@ export default class NestedComponent extends Field { * component tree. * * @param {string} key - The key of the component to retrieve. - * @param {function} fn - Called with the component once found. - * @return {Object} - The component that is located. + * @param {function} [fn] - Called with the component once found. + * @param {string} [originalPath] - The original path to the component. + * @return {Component} - The component that is located. */ getComponent(path, fn, originalPath) { originalPath = originalPath || getStringFromComponentPath(path); diff --git a/src/formio.form.js b/src/formio.form.js index b61b7df3bf..b533354653 100644 --- a/src/formio.form.js +++ b/src/formio.form.js @@ -11,6 +11,7 @@ import Utils from './utils'; import Evaluator from './utils/Evaluator'; import Licenses from './licenses'; import EventEmitter from './EventEmitter'; +import Webform from './Webform'; Formio.loadModules = (path = `${Formio.getApiUrl() }/externalModules.js`, name = 'externalModules') => { Formio.requireLibrary(name, name, path, true) @@ -126,4 +127,4 @@ export function useModule(defaultFn = null) { Formio.use = useModule(); // Export the components. -export { Components, Displays, Providers, Widgets, Templates, Utils, Form, Formio, Licenses, EventEmitter }; +export { Components, Displays, Providers, Widgets, Templates, Utils, Form, Formio, Licenses, EventEmitter, Webform };