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

package/lib/mjs/Form.d.ts

@@ -15,32 +15,32 @@ export default class Form extends Element {
      */
     /**
      * @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]
+     * @property {Function} [beforeSubmit] - Called before a submission is made.
+     * @property {Function} [beforeCancel] - Called before a cancel is made.
+     * @property {Function} [beforeNext] - Called before the next page is navigated to.
+     * @property {Function} [beforePrev] - Called before the previous page is navigated to.
+     * @property {Function} [attachComponent] - Called when a component is attached.
+     * @property {Function} [setDataValue] - Called when a data value is set.
+     * @property {Function} [addComponents] - Called when components are added.
+     * @property {Function} [addComponent] - Called when a component is added.
+     * @property {Function} [customValidation] - Called when a custom validation is made.
+     * @property {Function} [attachWebform] - Called when a webform is attached.
      */
     /**
      * @typedef {object} SanitizeConfig
-     * @property {string[]} [addAttr]
-     * @property {string[]} [addTags]
-     * @property {string[]} [allowedAttrs]
-     * @property {string[]} [allowedTags]
-     * @property {string[]} [allowedUriRegex]
-     * @property {string[]} [addUriSafeAttr]
+     * @property {string[]} [addAttr] - The html attributes to allow with sanitization.
+     * @property {string[]} [addTags] - The html tags to allow with sanitization.
+     * @property {string[]} [allowedAttrs] - The html attributes to allow with sanitization.
+     * @property {string[]} [allowedTags] - The html tags to allow with sanitization.
+     * @property {string[]} [allowedUriRegex] - The regex for allowed URIs.
+     * @property {string[]} [addUriSafeAttr] - The URI attributes to allow with sanitization.
      */
     /**
      * @typedef {object} ButtonSettings
-     * @property {boolean} [showPrevious]
-     * @property {boolean} [showNext]
-     * @property {boolean} [showCancel]
-     * @property {boolean} [showSubmit]
+     * @property {boolean} [showPrevious] - Show the previous button in wizard forms.
+     * @property {boolean} [showNext] - Show the next button in wizard forms.
+     * @property {boolean} [showCancel] - Show the cancel button in wizard forms.
+     * @property {boolean} [showSubmit] - Show the submit button in wizard forms.
      */
     /**
      * @typedef {object} FormOptions
@@ -212,15 +212,45 @@ export default class Form extends Element {
          * - The hooks for this form.
          */
         hooks?: {
+            /**
+             * - Called before a submission is made.
+             */
             beforeSubmit?: Function | undefined;
+            /**
+             * - Called before a cancel is made.
+             */
             beforeCancel?: Function | undefined;
+            /**
+             * - Called before the next page is navigated to.
+             */
             beforeNext?: Function | undefined;
+            /**
+             * - Called before the previous page is navigated to.
+             */
             beforePrev?: Function | undefined;
+            /**
+             * - Called when a component is attached.
+             */
             attachComponent?: Function | undefined;
+            /**
+             * - Called when a data value is set.
+             */
             setDataValue?: Function | undefined;
+            /**
+             * - Called when components are added.
+             */
             addComponents?: Function | undefined;
+            /**
+             * - Called when a component is added.
+             */
             addComponent?: Function | undefined;
+            /**
+             * - Called when a custom validation is made.
+             */
             customValidation?: Function | undefined;
+            /**
+             * - Called when a webform is attached.
+             */
             attachWebform?: Function | undefined;
         } | undefined;
         /**
@@ -251,20 +281,50 @@ export default class Form extends Element {
          * - The sanitize configuration for this form.
          */
         sanitizeConfig?: {
+            /**
+             * - The html attributes to allow with sanitization.
+             */
             addAttr?: string[] | undefined;
+            /**
+             * - The html tags to allow with sanitization.
+             */
             addTags?: string[] | undefined;
+            /**
+             * - The html attributes to allow with sanitization.
+             */
             allowedAttrs?: string[] | undefined;
+            /**
+             * - The html tags to allow with sanitization.
+             */
             allowedTags?: string[] | undefined;
+            /**
+             * - The regex for allowed URIs.
+             */
             allowedUriRegex?: string[] | undefined;
+            /**
+             * - The URI attributes to allow with sanitization.
+             */
             addUriSafeAttr?: string[] | undefined;
         } | undefined;
         /**
          * - The button settings for this form.
          */
         buttonSettings?: {
+            /**
+             * - Show the previous button in wizard forms.
+             */
             showPrevious?: boolean | undefined;
+            /**
+             * - Show the next button in wizard forms.
+             */
             showNext?: boolean | undefined;
+            /**
+             * - Show the cancel button in wizard forms.
+             */
             showCancel?: boolean | undefined;
+            /**
+             * - Show the submit button in wizard forms.
+             */
             showSubmit?: boolean | undefined;
         } | undefined;
         /**
@@ -300,13 +360,13 @@ export default class Form extends Element {
     /**
      * Create a new form instance provided the display of the form.
      * @param {string} display - The display of the form, either "wizard", "form", or "pdf"
-     * @returns {*}
+     * @returns {Webform|Wizard|PDF} - The new form instance for the display.
      */
-    create(display: string): any;
+    create(display: string): Webform | Wizard | PDF;
     /**
      * Sets the form. Either as JSON or a URL to a form JSON schema.
      * @param {string|object} formParam - Either the form JSON or the URL of the form json.
-     * @returns {*}
+     * @returns {void}
      */
     set form(formParam: object);
     /**
@@ -332,35 +392,38 @@ export default class Form extends Element {
     /**
      * Check Subdirectories path and provide correct options
      * @param {string} url - The the URL of the form json.
-     * @param {form} object - The form json.
-     * @param form
+     * @param {import('@formio/core').Form} form - The form json.
      * @returns {object} The initial options with base and project.
      */
-    getFormInitOptions(url: string, form: any): object;
-    setForm(formParam: any): any;
+    getFormInitOptions(url: string, form: import('@formio/core').Form): object;
+    /**
+     * Sets the form to the JSON schema of a form.
+     * @param {import('@formio/core').Form} formParam - The form JSON to set this form to.
+     * @returns {Promise<Webform|Wizard|PDF>} - The webform instance that was created.
+     */
+    setForm(formParam: import('@formio/core').Form): Promise<Webform | Wizard | PDF>;
     _form: any;
     getSubmission(formio: any, opts: any): any;
     /**
      * Changes the display of the form.
      * @param {string} display - The display to set this form. Either "wizard", "form", or "pdf"
-     * @returns {Promise<T>}
+     * @returns {Promise<Webform|Wizard|PDF>} - The form instance that was created after changing the display.
      */
-    setDisplay(display: string): Promise<T>;
+    setDisplay(display: string): Promise<Webform | Wizard | PDF>;
     empty(): void;
     /**
      * Sanitize an html string.
-     * @param string
-     * @param dirty
-     * @param forceSanitize
-     * @returns {*}
+     * @param {string} dirty - The dirty html string to sanitize.
+     * @param {boolean} forceSanitize - If the string should be force sanitized.
+     * @returns {string} - The sanitized html string.
      */
-    sanitize(dirty: any, forceSanitize: any): any;
+    sanitize(dirty: string, forceSanitize: boolean): string;
     setContent(element: any, content: any, forceSanitize: any): boolean;
     /**
      * Build a new form.
-     * @returns {Promise<T>}
+     * @returns {Promise<Webform|Wizard|PDF>} - The form instance that was created.
      */
-    build(): Promise<T>;
+    build(): Promise<Webform | Wizard | PDF>;
     render(): Promise<any>;
     attach(element: any): any;
 }

package/lib/mjs/Form.js

@@ -18,32 +18,32 @@ export default class Form extends Element {
      */
     /**
      * @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]
+     * @property {Function} [beforeSubmit] - Called before a submission is made.
+     * @property {Function} [beforeCancel] - Called before a cancel is made.
+     * @property {Function} [beforeNext] - Called before the next page is navigated to.
+     * @property {Function} [beforePrev] - Called before the previous page is navigated to.
+     * @property {Function} [attachComponent] - Called when a component is attached.
+     * @property {Function} [setDataValue] - Called when a data value is set.
+     * @property {Function} [addComponents] - Called when components are added.
+     * @property {Function} [addComponent] - Called when a component is added.
+     * @property {Function} [customValidation] - Called when a custom validation is made.
+     * @property {Function} [attachWebform] - Called when a webform is attached.
      */
     /**
      * @typedef {object} SanitizeConfig
-     * @property {string[]} [addAttr]
-     * @property {string[]} [addTags]
-     * @property {string[]} [allowedAttrs]
-     * @property {string[]} [allowedTags]
-     * @property {string[]} [allowedUriRegex]
-     * @property {string[]} [addUriSafeAttr]
+     * @property {string[]} [addAttr] - The html attributes to allow with sanitization.
+     * @property {string[]} [addTags] - The html tags to allow with sanitization.
+     * @property {string[]} [allowedAttrs] - The html attributes to allow with sanitization.
+     * @property {string[]} [allowedTags] - The html tags to allow with sanitization.
+     * @property {string[]} [allowedUriRegex] - The regex for allowed URIs.
+     * @property {string[]} [addUriSafeAttr] - The URI attributes to allow with sanitization.
      */
     /**
      * @typedef {object} ButtonSettings
-     * @property {boolean} [showPrevious]
-     * @property {boolean} [showNext]
-     * @property {boolean} [showCancel]
-     * @property {boolean} [showSubmit]
+     * @property {boolean} [showPrevious] - Show the previous button in wizard forms.
+     * @property {boolean} [showNext] - Show the next button in wizard forms.
+     * @property {boolean} [showCancel] - Show the cancel button in wizard forms.
+     * @property {boolean} [showSubmit] - Show the submit button in wizard forms.
      */
     /**
      * @typedef {object} FormOptions
@@ -189,7 +189,7 @@ export default class Form extends Element {
     /**
      * Create a new form instance provided the display of the form.
      * @param {string} display - The display of the form, either "wizard", "form", or "pdf"
-     * @returns {*}
+     * @returns {Webform|Wizard|PDF} - The new form instance for the display.
      */
     create(display) {
         if (this.options && (this.options.flatten || this.options.renderMode === 'flat')) {
@@ -207,7 +207,7 @@ export default class Form extends Element {
     /**
      * Sets the form. Either as JSON or a URL to a form JSON schema.
      * @param {string|object} formParam - Either the form JSON or the URL of the form json.
-     * @returns {*}
+     * @returns {void}
      */
     set form(formParam) {
         this.setForm(formParam);
@@ -236,8 +236,7 @@ export default class Form extends Element {
     /**
      * Check Subdirectories path and provide correct options
      * @param {string} url - The the URL of the form json.
-     * @param {form} object - The form json.
-     * @param form
+     * @param {import('@formio/core').Form} form - The form json.
      * @returns {object} The initial options with base and project.
      */
     getFormInitOptions(url, form) {
@@ -263,6 +262,11 @@ export default class Form extends Element {
         }
         return {};
     }
+    /**
+     * Sets the form to the JSON schema of a form.
+     * @param {import('@formio/core').Form} formParam - The form JSON to set this form to.
+     * @returns {Promise<Webform|Wizard|PDF>} - The webform instance that was created.
+     */
     setForm(formParam) {
         let result;
         formParam = formParam || this.form;
@@ -331,7 +335,7 @@ export default class Form extends Element {
     /**
      * Changes the display of the form.
      * @param {string} display - The display to set this form. Either "wizard", "form", or "pdf"
-     * @returns {Promise<T>}
+     * @returns {Promise<Webform|Wizard|PDF>} - The form instance that was created after changing the display.
      */
     setDisplay(display) {
         if ((this.display === display) && this.instance) {
@@ -372,10 +376,9 @@ export default class Form extends Element {
     }
     /**
      * Sanitize an html string.
-     * @param string
-     * @param dirty
-     * @param forceSanitize
-     * @returns {*}
+     * @param {string} dirty - The dirty html string to sanitize.
+     * @param {boolean} forceSanitize - If the string should be force sanitized.
+     * @returns {string} - The sanitized html string.
      */
     sanitize(dirty, forceSanitize) {
         // If Sanitize is turned off
@@ -393,7 +396,7 @@ export default class Form extends Element {
     }
     /**
      * Build a new form.
-     * @returns {Promise<T>}
+     * @returns {Promise<Webform|Wizard|PDF>} - The form instance that was created.
      */
     build() {
         if (!this.instance) {
@@ -448,14 +451,16 @@ export default class Form extends Element {
 // Allow simple embedding.
 Formio.embedForm = (embed) => Form.embed(embed);
 /**
- * Factory that creates a new form based on the form parameters.
- * @param element {HMTLElement} - The HTML Element to add this form to.
- * @param form {string|Object} - The src of the form, or a form object.
- * @param options {Object} - The options to create this form.
- * @param {...any} args
- * @returns {Promise} - When the form is instance is ready.
+ * Creates an easy to use interface for embedding webforms, pdfs, and wizards into your application.
+ * @param {object} elementOrForm - The DOM element you wish to render this form within, or the form definition.
+ * @param {object | string | FormOptions} formOrOptions - A Form JSON schema, the URL of a hosted form, or the form options.
+ * @param {FormOptions} [options] - The options to create a new form instance.
+ * @returns {Promise<Webform|Wizard|PDF>} - The form instance that was created.
+ * @example
+ * import { Formio } from '@formio/js';
+ * Formio.createForm(document.getElementById('formio'), 'https://examples.form.io/example');
  */
-Formio.createForm = (...args) => {
-    return (new Form(...args)).ready;
+Formio.createForm = (elementOrForm, formOrOptions, options) => {
+    return (new Form(elementOrForm, formOrOptions, options)).ready;
 };
 Formio.Form = Form;

package/lib/mjs/InlineEmbed.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Inline embed a form within a webpage.
+ * @param {*} config - Configuration to configure how the inline embed is rendered.
+ */
+export function embed(config?: any): void;
+export { Formio };
+import { Formio } from './Embed';

package/lib/mjs/InlineEmbed.js

@@ -0,0 +1,105 @@
+import { Formio } from './Embed';
+/**
+ * Inline embed a form within a webpage.
+ * @param {*} config - Configuration to configure how the inline embed is rendered.
+ */
+export function embed(config = {}) {
+    const scripts = document.getElementsByTagName('script');
+    config = Object.assign({}, window.FormioConfig || {}, config);
+    let thisScript = null;
+    let i = scripts.length;
+    const scriptName = config.scriptName || 'formio.embed.';
+    while (i--) {
+        if (scripts[i].src && (scripts[i].src.indexOf(scriptName) !== -1)) {
+            thisScript = scripts[i];
+            break;
+        }
+    }
+    if (thisScript) {
+        const query = {};
+        const queryString = thisScript.src.replace(/^[^?]+\??/, '');
+        queryString.replace(/\?/g, '&').split('&').forEach((item) => {
+            query[item.split('=')[0]] = item.split('=')[1] && decodeURIComponent(item.split('=')[1]);
+        });
+        let scriptSrc = thisScript.src.replace(/^([^?]+).*/, '$1').split('/');
+        scriptSrc.pop();
+        if (config.formioPath) {
+            config.formioPath(scriptSrc);
+        }
+        scriptSrc = scriptSrc.join('/');
+        const debug = (query.debug === 'true' || query.debug === '1');
+        const renderer = debug ? 'formio.form' : 'formio.form.min';
+        Formio.config = Object.assign({
+            script: query.script || (`${config.updatePath ? config.updatePath() : scriptSrc}/${renderer}.js`),
+            style: query.styles || (`${config.updatePath ? config.updatePath() : scriptSrc}/${renderer}.css`),
+            cdn: query.cdn,
+            class: (query.class || 'formio-form-wrapper'),
+            src: query.src,
+            form: null,
+            submission: null,
+            project: query.project,
+            base: query.base || 'https://api.form.io',
+            submit: query.submit,
+            includeLibs: (query.libs === 'true' || query.libs === '1'),
+            template: query.template,
+            debug: debug,
+            config: {},
+            redirect: (query.return || query.redirect),
+            embedCSS: (`${config.updatePath ? config.updatePath() : scriptSrc}/formio.embed.css`),
+            success: query.success || 'Thank you for your submission!',
+            before: null,
+            after: null
+        }, config);
+        const form = (Formio.config.form || Formio.config.src);
+        if (form) {
+            Formio.debug('Embedding Configuration', config);
+            if (Formio.config.addPremiumLib) {
+                Formio.config.addPremiumLib(Formio.config, scriptSrc);
+            }
+            // The id for this embedded form.
+            Formio.config.id = `formio-${Math.random().toString(36).substring(7)}`;
+            Formio.debug('Creating form element');
+            const element = Formio.createElement('div', {
+                'id': Formio.config.id,
+                class: Formio.config.class
+            });
+            // insertAfter doesn't exist, but effect is identical.
+            thisScript.parentNode.insertBefore(element, thisScript.parentNode.firstElementChild.nextSibling);
+            Formio.createForm(element, form, Formio.config.config).then((instance) => {
+                if (Formio.config.submit) {
+                    instance.nosubmit = true;
+                }
+                // Configure a redirect.
+                instance.on('submit', (submission) => {
+                    Formio.debug("on('submit')", submission);
+                    if (Formio.config.submit) {
+                        Formio.debug(`Sending submission to ${Formio.config.submit}`);
+                        const headers = {
+                            'content-type': 'application/json'
+                        };
+                        const token = Formio.FormioClass.getToken();
+                        if (token) {
+                            headers['x-jwt-token'] = token;
+                        }
+                        Formio.FormioClass.fetch(Formio.config.submit, {
+                            body: JSON.stringify(submission),
+                            headers: headers,
+                            method: 'POST',
+                            mode: 'cors',
+                        })
+                            .then(resp => resp.json())
+                            .then(submission => Formio.submitDone(instance, submission));
+                    }
+                    else {
+                        Formio.submitDone(instance, submission);
+                    }
+                });
+            });
+        }
+    }
+    else {
+        // Show an error if the script cannot be found.
+        document.write('<span>Could not locate the Embedded form.</span>');
+    }
+}
+export { Formio };

package/lib/mjs/PDF.d.ts

@@ -11,23 +11,24 @@ export default class PDF extends Webform {
     iframeElement: any;
     /**
      * Get the submission from the iframe.
-     * @returns {Promise<any>}
+     * @returns {Promise<any>} - The submission from the iframe.
      */
     getSubmission(): Promise<any>;
     /**
      * Ensure we have the submission from the iframe before we submit the form.
-     * @param options
-     * @returns {*}
+     * @param {any} options - The options for submission.
+     * @returns {Promise<any>} - Resolves when the form is submitted.
      */
-    submitForm(options?: {}): any;
+    submitForm(options?: any): Promise<any>;
     getSrc(): string;
     setForm(form: any, flags?: {}): Promise<void>;
     /**
      * Set's the value of this form component.
-     * @param submission
-     * @param flags
+     * @param {import('@formio/core').Submission} submission - The submission JSON to set the value of this form.
+     * @param {any} flags - The flags to use when setting the submission.
+     * @returns {boolean} - If the value changed or not.
      */
-    setValue(submission: any, flags?: {}): boolean;
+    setValue(submission: import('@formio/core').Submission, flags?: any): boolean;
     postMessage(message: any): void;
     iframeFormSetUp: boolean | undefined;
     focusOnComponent(key: any): void;

package/lib/mjs/PDF.js

@@ -138,7 +138,7 @@ export default class PDF extends Webform {
     }
     /**
      * Get the submission from the iframe.
-     * @returns {Promise<any>}
+     * @returns {Promise<any>} - The submission from the iframe.
      */
     getSubmission() {
         return new Promise((resolve) => {
@@ -148,8 +148,8 @@ export default class PDF extends Webform {
     }
     /**
      * Ensure we have the submission from the iframe before we submit the form.
-     * @param options
-     * @returns {*}
+     * @param {any} options - The options for submission.
+     * @returns {Promise<any>} - Resolves when the form is submitted.
      */
     submitForm(options = {}) {
         this.postMessage({ name: 'getErrors' });
@@ -191,8 +191,9 @@ export default class PDF extends Webform {
     }
     /**
      * Set's the value of this form component.
-     * @param submission
-     * @param flags
+     * @param {import('@formio/core').Submission} submission - The submission JSON to set the value of this form.
+     * @param {any} flags - The flags to use when setting the submission.
+     * @returns {boolean} - If the value changed or not.
      */
     setValue(submission, flags = {}) {
         const changed = super.setValue(submission, flags);

package/lib/mjs/Webform.d.ts

@@ -83,9 +83,6 @@
  * @property {boolean} [building] - If we are in the process of building the form.
  * @property {number} [zoom] - The zoom for PDF forms.
  */
-/**
- * Renders a Form.io form within the webpage.
- */
 declare class Webform extends NestedDataComponent {
     /**
      * Creates a new Form instance.

package/lib/mjs/Webform.js

@@ -129,9 +129,6 @@ function getOptions(options) {
  * @property {boolean} [building] - If we are in the process of building the form.
  * @property {number} [zoom] - The zoom for PDF forms.
  */
-/**
- * Renders a Form.io form within the webpage.
- */
 export default class Webform extends NestedDataComponent {
     /**
      * @type {import('Form').FormOptions} - the options for this Webform.
@@ -142,14 +139,14 @@ export default class Webform extends NestedDataComponent {
      * @param {HTMLElement | object | import('Form').FormOptions} [elementOrOptions] - The DOM element to render this form within or the options to create this form instance.
      * @param {import('Form').FormOptions} [options] - The options to create a new form instance.
      */
-    constructor(elementOrOptions, options) {
+    constructor(elementOrOptions, options = undefined) {
         let element, formOptions;
         if (elementOrOptions instanceof HTMLElement || options) {
             element = elementOrOptions;
-            formOptions = options;
+            formOptions = options || {};
         }
         else {
-            formOptions = elementOrOptions;
+            formOptions = elementOrOptions || {};
         }
         super(null, getOptions(formOptions));
         this.setElement(element);
@@ -168,7 +165,7 @@ export default class Webform extends NestedDataComponent {
         this._loading = false;
         this._form = {};
         this.draftEnabled = false;
-        this.savingDraft = true;
+        this.savingDraft = false;
         if (this.options.saveDraftThrottle) {
             this.triggerSaveDraft = _.throttle(this.saveDraft.bind(this), this.options.saveDraftThrottle);
         }
@@ -265,14 +262,20 @@ export default class Webform extends NestedDataComponent {
         // Set language after everything is established.
         this.language = this.i18next.language;
         // See if we need to restore the draft from a user.
-        if (this.options.saveDraft && !this.options.skipDraftRestore) {
-            this.formReady.then(() => {
-                const user = Formio.getUser();
-                // Only restore a draft if the submission isn't explicitly set.
-                if (user && !this.submissionSet) {
-                    this.restoreDraft(user._id);
-                }
-            });
+        if (this.options.saveDraft) {
+            if (this.options.skipDraftRestore) {
+                this.draftEnabled = true;
+                this.savingDraft = false;
+            }
+            else {
+                this.formReady.then(() => {
+                    const user = Formio.getUser();
+                    // Only restore a draft if the submission isn't explicitly set.
+                    if (user && !this.submissionSet) {
+                        this.restoreDraft(user._id);
+                    }
+                });
+            }
         }
         this.component.clearOnHide = false;
         // Ensure the root is set to this component.