@oneblink/apps-react 3.2.0-beta.1 → 4.0.0-beta.10

package/dist/OneBlinkForm.js

@@ -1,9 +1,555 @@
 import * as React from 'react';
 import OneBlinkFormBase from './OneBlinkFormBase';
 import useFormSubmissionState from './hooks/useFormSubmissionState';
+/**
+ * Similar to {@link OneBlinkForm}, however requires props to control the
+ * `definition` and `submission` values.
+ *
+ * #### Example
+ *
+ * ```tsx
+ * import React from 'react'
+ * import ReactDOM from 'react-dom'
+ * import { FormTypes } from '@oneblink/types'
+ * import {
+ *   OneBlinkAppsError,
+ *   draftService,
+ *   submissionService,
+ * } from '@oneblink/apps'
+ * import {
+ *   IsOfflineContextProvider,
+ *   OneBlinkFormControlled,
+ *   useIsMounted,
+ *   useFormSubmissionState,
+ * } from '@oneblink/apps-react'
+ * import '@oneblink/apps-react/dist/styles.css'
+ *
+ * const captchaSiteKey = 'ENTER_YOUR_SITE_KEY_HERE'
+ * const googleMapsApiKey = 'ENTER_YOUR_MAPS_API_KEY_HERE'
+ * const formsAppId = 1
+ * const form: FormTypes.Form = {
+ *   id: 1,
+ *   name: 'Name of Form',
+ *   description: '',
+ *   organisationId: 'abc123',
+ *   formsAppEnvironmentId: 1,
+ *   formsAppIds: [],
+ *   elements: [],
+ *   isAuthenticated: false,
+ *   isMultiPage: false,
+ *   isInfoPage: false,
+ *   publishStartDate: null,
+ *   publishEndDate: null,
+ *   postSubmissionAction: 'FORMS_LIBRARY',
+ *   submissionEvents: [],
+ *   tags: [],
+ * }
+ * const initialSubmission: Record<string, unknown> = {
+ *   data: 1,
+ * }
+ *
+ * function FormContainer() {
+ *   const isMounted = useIsMounted()
+ *
+ *   const [{ definition, submission }, setFormSubmission] =
+ *     useFormSubmissionState(form, initialSubmission)
+ *
+ *   const [{ isSavingDraft, saveDraftError }, setSaveDraftState] =
+ *     React.useState({
+ *       isSavingDraft: false,
+ *       saveDraftError: null,
+ *     })
+ *
+ *   const [
+ *     { isSubmitting, submitError, formSubmissionResult },
+ *     setSubmitState,
+ *   ] = React.useState({
+ *     formSubmissionResult: null,
+ *     isSubmitting: false,
+ *     submitError: null,
+ *   })
+ *
+ *   const handleSubmit = React.useCallback(
+ *     async (newFormSubmission: FormTypes.NewFormSubmission) => {
+ *       const formSubmission: FormSubmission = Object.assign(
+ *         {},
+ *         newFormSubmission,
+ *         {
+ *           formsAppId,
+ *           jobId: null,
+ *           externalId: null,
+ *           draftId: null,
+ *           preFillFormDataId: null,
+ *         },
+ *       )
+ *
+ *       setSubmitState({
+ *         formSubmissionResult: null,
+ *         submitError: null,
+ *         isSubmitting: true,
+ *       })
+ *
+ *       try {
+ *         const newFormSubmissionResult = await submissionService.submit({
+ *           formSubmission,
+ *         })
+ *         if (
+ *           newFormSubmissionResult.isOffline &&
+ *           !newFormSubmissionResult.isInPendingQueue
+ *         ) {
+ *           throw new OneBlinkAppsError(
+ *             'You cannot submit this form while offline, please try again when connectivity is restored.',
+ *             {
+ *               isOffline: true,
+ *             },
+ *           )
+ *         }
+ *
+ *         if (isMounted.current) {
+ *           setSubmitState({
+ *             formSubmissionResult: newFormSubmissionResult,
+ *             isSubmitting: false,
+ *             submitError: null,
+ *           })
+ *         }
+ *       } catch (error) {
+ *         if (isMounted.current) {
+ *           setSubmitState({
+ *             formSubmissionResult: null,
+ *             isSubmitting: false,
+ *             submitError: error,
+ *           })
+ *         }
+ *       }
+ *     },
+ *     [isMounted],
+ *   )
+ *
+ *   const handleSaveDraft = React.useCallback(
+ *     async (newDraftSubmission: FormTypes.NewDraftSubmission) => {
+ *       const draftSubmission: FormTypes.DraftSubmission = {
+ *         ...newDraftSubmission,
+ *         formsAppId,
+ *       }
+ *       setSaveDraftState({
+ *         saveDraftError: null,
+ *         isSavingDraft: true,
+ *       })
+ *
+ *       try {
+ *         await draftService.addDraft(
+ *           {
+ *             title: form.name,
+ *             formId: form.id,
+ *             externalId: null,
+ *             jobId: null,
+ *           },
+ *           draftSubmission,
+ *         )
+ *
+ *         if (isMounted.current) {
+ *           setSaveDraftState({
+ *             saveDraftError: null,
+ *             isSavingDraft: false,
+ *           })
+ *         }
+ *       } catch (error) {
+ *         if (isMounted.current) {
+ *           setSaveDraftState({
+ *             saveDraftError: error,
+ *             isSavingDraft: false,
+ *           })
+ *         }
+ *       }
+ *     },
+ *     [isMounted],
+ *   )
+ *
+ *   const handleCancel = React.useCallback(() => {
+ *     // handle cancel here...
+ *   }, [])
+ *
+ *   if (isSubmitting) {
+ *     // Render submitting animation/loading
+ *   }
+ *
+ *   if (submitError) {
+ *     // Render error while submitting
+ *   }
+ *
+ *   if (isSavingDraft) {
+ *     // Render saving draft animation/loading
+ *   }
+ *
+ *   if (saveDraftError) {
+ *     // Render error while saving draft
+ *   }
+ *
+ *   if (formSubmissionResult) {
+ *     // Render submission success
+ *   }
+ *
+ *   return (
+ *     <OneBlinkFormControlled
+ *       captchaSiteKey={captchaSiteKey}
+ *       googleMapsApiKey={googleMapsApiKey}
+ *       formsAppId={formsAppId}
+ *       definition={definition}
+ *       submission={submission}
+ *       setFormSubmission={setFormSubmission}
+ *       onCancel={handleCancel}
+ *       onSubmit={handleSubmit}
+ *       onSaveDraft={handleSaveDraft}
+ *     />
+ *   )
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <IsOfflineContextProvider>
+ *       <FormContainer />
+ *     </IsOfflineContextProvider>
+ *   )
+ * }
+ *
+ * const root = document.getElementById('root')
+ * if (root) {
+ *   ReactDOM.render(<App />, root)
+ * }
+ * ```
+ *
+ * #### Implementing Controlled Auto Save
+ *
+ * The {@link OneBlinkAutoSaveForm} component does not offer props to allow for a
+ * controlled form (i.e. having access to `submission` and `definition` values).
+ * To implement a controlled version of the `<OneBlinkAutoSaveForm />`
+ * component, use the example component below.
+ *
+ * ```tsx
+ * import * as React from 'react'
+ * import {
+ *   OneBlinkAutoSaveForm,
+ *   OneBlinkFormControlled,
+ *   useFormSubmissionAutoSaveState,
+ * } from '@oneblink/apps-react'
+ *
+ * function OneBlinkAutoSaveFormControlled({
+ *   form,
+ *   initialSubmission,
+ *   autoSaveKey,
+ *   onCancel,
+ *   onSubmit,
+ *   onSaveDraft,
+ *   ...props
+ * }: React.ComponentProps<typeof OneBlinkAutoSaveForm>) {
+ *   const {
+ *     definition,
+ *     submission,
+ *     isLoadingAutoSaveSubmission,
+ *     isAutoSaveSubmissionAvailable,
+ *     startNewSubmission,
+ *     continueAutoSaveSubmission,
+ *     handleSubmit,
+ *     handleCancel,
+ *     handleSaveDraft,
+ *     setFormSubmission,
+ *   } = useFormSubmissionAutoSaveState({
+ *     form,
+ *     initialSubmission,
+ *     autoSaveKey,
+ *     onCancel,
+ *     onSubmit,
+ *     onSaveDraft,
+ *   })
+ *
+ *   // This is just an example of how you could intercept
+ *   // the change event when a user enters/selects a value
+ *   // on the form.
+ *   const customSetFormSubmission = React.useCallback(
+ *     (formSubmission) => {
+ *       setFormSubmission((currentFormSubmission) => {
+ *         const newFormSubmission =
+ *           typeof formSubmission === 'function'
+ *             ? formSubmission(currentFormSubmission)
+ *             : formSubmission
+ *
+ *         // This is where you can access the updated
+ *         // submission data or form definition.
+ *         // You could even change the form definition
+ *         // programmatically based on user inputs.
+ *         console.log(
+ *           'A change has occurred to the submission',
+ *           newFormSubmission.submission,
+ *         )
+ *         newFormSubmission.definition.isInfoPage =
+ *           !newFormSubmission.submission.doesTheUserNeedToSubmit
+ *
+ *         return newFormSubmission
+ *       })
+ *     },
+ *     [setFormSubmission],
+ *   )
+ *
+ *   if (isLoadingAutoSaveSubmission) {
+ *     return <p>Checking for auto save data...</p>
+ *   }
+ *
+ *   if (isAutoSaveSubmissionAvailable) {
+ *     return (
+ *       <>
+ *         <p>Do you want to use the auto save data?</p>
+ *         <button onClick={startNewSubmission}>No, start again</button>
+ *         <button onClick={continueAutoSaveSubmission}>
+ *           Yes, continue
+ *         </button>
+ *       </>
+ *     )
+ *   }
+ *
+ *   return (
+ *     <OneBlinkFormControlled
+ *       {...props}
+ *       submission={submission}
+ *       definition={definition}
+ *       onCancel={handleCancel}
+ *       onSubmit={handleSubmit}
+ *       onSaveDraft={handleSaveDraft}
+ *       setFormSubmission={customSetFormSubmission}
+ *     />
+ *   )
+ * }
+ *
+ * export default React.memo(OneBlinkAutoSaveFormControlled)
+ * ```
+ *
+ * @param props
+ * @returns
+ * @group Components
+ */
 const OneBlinkFormControlled = React.memo(function OneBlinkFormControlled(props) {
     return React.createElement(OneBlinkFormBase, { ...props, isReadOnly: false });
 });
+/**
+ * Component for rendering a OneBlink Form. This component will render the
+ * submit, cancel and save draft buttons but it is up to the developer to
+ * implement what happens when those buttons are clicked.
+ *
+ * It is also recommended to import the `css` from this library as well.
+ *
+ * ```js
+ * import { OneBlinkForm } from '@oneblink/apps-react'
+ * import '@oneblink/apps-react/dist/styles.css'
+ * ```
+ *
+ * #### Example
+ *
+ * ```tsx
+ * import React from 'react'
+ * import ReactDOM from 'react-dom'
+ * import { FormTypes } from '@oneblink/types'
+ * import {
+ *   OneBlinkAppsError,
+ *   draftService,
+ *   submissionService,
+ * } from '@oneblink/apps'
+ * import {
+ *   IsOfflineContextProvider,
+ *   OneBlinkForm,
+ *   useIsMounted,
+ * } from '@oneblink/apps-react'
+ * import '@oneblink/apps-react/dist/styles.css'
+ *
+ * const captchaSiteKey = 'ENTER_YOUR_SITE_KEY_HERE'
+ * const googleMapsApiKey = 'ENTER_YOUR_MAPS_API_KEY_HERE'
+ * const formsAppId = 1
+ * const form: FormTypes.Form = {
+ *   id: 1,
+ *   name: 'Name of Form',
+ *   description: '',
+ *   organisationId: 'abc123',
+ *   formsAppEnvironmentId: 1,
+ *   formsAppIds: [],
+ *   elements: [],
+ *   isAuthenticated: false,
+ *   isMultiPage: false,
+ *   isInfoPage: false,
+ *   publishStartDate: null,
+ *   publishEndDate: null,
+ *   postSubmissionAction: 'FORMS_LIBRARY',
+ *   submissionEvents: [],
+ *   tags: [],
+ * }
+ *
+ * function FormContainer() {
+ *   const isMounted = useIsMounted()
+ *
+ *   const [{ isSavingDraft, saveDraftError }, setSaveDraftState] =
+ *     React.useState({
+ *       isSavingDraft: false,
+ *       saveDraftError: null,
+ *     })
+ *
+ *   const [
+ *     { isSubmitting, submitError, formSubmissionResult },
+ *     setSubmitState,
+ *   ] = React.useState({
+ *     formSubmissionResult: null,
+ *     isSubmitting: false,
+ *     submitError: null,
+ *   })
+ *
+ *   const handleSubmit = React.useCallback(
+ *     async (newFormSubmission: FormTypes.NewFormSubmission) => {
+ *       const formSubmission: FormSubmission = Object.assign(
+ *         {},
+ *         newFormSubmission,
+ *         {
+ *           formsAppId,
+ *           jobId: null,
+ *           externalId: null,
+ *           draftId: null,
+ *           preFillFormDataId: null,
+ *         },
+ *       )
+ *
+ *       setSubmitState({
+ *         formSubmissionResult: null,
+ *         submitError: null,
+ *         isSubmitting: true,
+ *       })
+ *
+ *       try {
+ *         const newFormSubmissionResult = await submissionService.submit({
+ *           formSubmission,
+ *         })
+ *         if (
+ *           newFormSubmissionResult.isOffline &&
+ *           !newFormSubmissionResult.isInPendingQueue
+ *         ) {
+ *           throw new OneBlinkAppsError(
+ *             'You cannot submit this form while offline, please try again when connectivity is restored.',
+ *             {
+ *               isOffline: true,
+ *             },
+ *           )
+ *         }
+ *
+ *         if (isMounted.current) {
+ *           setSubmitState({
+ *             formSubmissionResult: newFormSubmissionResult,
+ *             isSubmitting: false,
+ *             submitError: null,
+ *           })
+ *         }
+ *       } catch (error) {
+ *         if (isMounted.current) {
+ *           setSubmitState({
+ *             formSubmissionResult: null,
+ *             isSubmitting: false,
+ *             submitError: error,
+ *           })
+ *         }
+ *       }
+ *     },
+ *     [isMounted],
+ *   )
+ *
+ *   const handleSaveDraft = React.useCallback(
+ *     async (newDraftSubmission: FormTypes.NewDraftSubmission) => {
+ *       const draftSubmission: FormTypes.DraftSubmission = {
+ *         ...newDraftSubmission,
+ *         formsAppId,
+ *       }
+ *       setSaveDraftState({
+ *         saveDraftError: null,
+ *         isSavingDraft: true,
+ *       })
+ *
+ *       try {
+ *         await draftService.addDraft(
+ *           {
+ *             title: form.name,
+ *             formId: form.id,
+ *             externalId: null,
+ *             jobId: null,
+ *           },
+ *           draftSubmission,
+ *         )
+ *
+ *         if (isMounted.current) {
+ *           setSaveDraftState({
+ *             saveDraftError: null,
+ *             isSavingDraft: false,
+ *           })
+ *         }
+ *       } catch (error) {
+ *         if (isMounted.current) {
+ *           setSaveDraftState({
+ *             saveDraftError: error,
+ *             isSavingDraft: false,
+ *           })
+ *         }
+ *       }
+ *     },
+ *     [isMounted],
+ *   )
+ *
+ *   const handleCancel = React.useCallback(() => {
+ *     // handle cancel here...
+ *   }, [isMounted])
+ *
+ *   if (isSubmitting) {
+ *     // Render submitting animation/loading
+ *   }
+ *
+ *   if (submitError) {
+ *     // Render error while submitting
+ *   }
+ *
+ *   if (isSavingDraft) {
+ *     // Render saving draft animation/loading
+ *   }
+ *
+ *   if (saveDraftError) {
+ *     // Render error while saving draft
+ *   }
+ *
+ *   if (formSubmissionResult) {
+ *     // Render submission success
+ *   }
+ *
+ *   return (
+ *     <OneBlinkForm
+ *       captchaSiteKey={captchaSiteKey}
+ *       googleMapsApiKey={googleMapsApiKey}
+ *       formsAppId={formsAppId}
+ *       form={form}
+ *       onCancel={handleCancel}
+ *       onSubmit={handleSubmit}
+ *       onSaveDraft={handleSaveDraft}
+ *       attachmentRetentionInDays={1}
+ *     />
+ *   )
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <IsOfflineContextProvider>
+ *       <FormContainer />
+ *     </IsOfflineContextProvider>
+ *   )
+ * }
+ *
+ * const root = document.getElementById('root')
+ * if (root) {
+ *   ReactDOM.render(<App />, root)
+ * }
+ * ```
+ *
+ * @param props
+ * @returns
+ * @group Components
+ */
 const OneBlinkFormUncontrolled = React.memo(function OneBlinkFormUncontrolled({ form, initialSubmission, resumeAtElement, ...props }) {
     const [{ definition, submission, lastElementUpdated }, setFormSubmission] = useFormSubmissionState(form, initialSubmission, resumeAtElement);
     return (React.createElement(OneBlinkFormBase, { ...props, isReadOnly: false, definition: definition, submission: submission, setFormSubmission: setFormSubmission, lastElementUpdated: lastElementUpdated }));

package/dist/OneBlinkForm.js.map

@@ -1 +1 @@
-{"version":3,"file":"OneBlinkForm.js","sourceRoot":"","sources":["../src/OneBlinkForm.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B,OAAO,gBAGN,MAAM,oBAAoB,CAAA;AAC3B,OAAO,sBAAsB,MAAM,gCAAgC,CAAA;AAGnE,MAAM,sBAAsB,GAAG,KAAK,CAAC,IAAI,CAAC,SAAS,sBAAsB,CACvE,KAAkC;IAElC,OAAO,oBAAC,gBAAgB,OAAK,KAAK,EAAE,UAAU,EAAE,KAAK,GAAI,CAAA;AAC3D,CAAC,CAAC,CAAA;AAQF,MAAM,wBAAwB,GAAG,KAAK,CAAC,IAAI,CAAC,SAAS,wBAAwB,CAAC,EAC5E,IAAI,EACJ,iBAAiB,EACjB,eAAe,EACf,GAAG,KAAK,EACsB;IAC9B,MAAM,CAAC,EAAE,UAAU,EAAE,UAAU,EAAE,kBAAkB,EAAE,EAAE,iBAAiB,CAAC,GACvE,sBAAsB,CAAC,IAAI,EAAE,iBAAiB,EAAE,eAAe,CAAC,CAAA;IAClE,OAAO,CACL,oBAAC,gBAAgB,OACX,KAAK,EACT,UAAU,EAAE,KAAK,EACjB,UAAU,EAAE,UAAU,EACtB,UAAU,EAAE,UAAU,EACtB,iBAAiB,EAAE,iBAAiB,EACpC,kBAAkB,EAAE,kBAAkB,GACtC,CACH,CAAA;AACH,CAAC,CAAC,CAAA;AAEF,OAAO,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,CAAA","sourcesContent":["import * as React from 'react'\nimport { FormTypes } from '@oneblink/types'\nimport OneBlinkFormBase, {\n  BaseProps,\n  ControlledProps,\n} from './OneBlinkFormBase'\nimport useFormSubmissionState from './hooks/useFormSubmissionState'\nimport { FormSubmissionModel } from './types/form'\n\nconst OneBlinkFormControlled = React.memo(function OneBlinkFormControlled(\n  props: BaseProps & ControlledProps,\n) {\n  return <OneBlinkFormBase {...props} isReadOnly={false} />\n})\n\ntype UncontrolledProps = {\n  form: FormTypes.Form\n  initialSubmission?: FormSubmissionModel\n  resumeAtElement?: FormTypes.FormElement\n}\n\nconst OneBlinkFormUncontrolled = React.memo(function OneBlinkFormUncontrolled({\n  form,\n  initialSubmission,\n  resumeAtElement,\n  ...props\n}: BaseProps & UncontrolledProps) {\n  const [{ definition, submission, lastElementUpdated }, setFormSubmission] =\n    useFormSubmissionState(form, initialSubmission, resumeAtElement)\n  return (\n    <OneBlinkFormBase\n      {...props}\n      isReadOnly={false}\n      definition={definition}\n      submission={submission}\n      setFormSubmission={setFormSubmission}\n      lastElementUpdated={lastElementUpdated}\n    />\n  )\n})\n\nexport { OneBlinkFormControlled, OneBlinkFormUncontrolled }\n"]}
+{"version":3,"file":"OneBlinkForm.js","sourceRoot":"","sources":["../src/OneBlinkForm.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B,OAAO,gBAGN,MAAM,oBAAoB,CAAA;AAC3B,OAAO,sBAAsB,MAAM,gCAAgC,CAAA;AAInE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoUG;AACH,MAAM,sBAAsB,GAAG,KAAK,CAAC,IAAI,CAAC,SAAS,sBAAsB,CACvE,KAA0D;IAE1D,OAAO,oBAAC,gBAAgB,OAAK,KAAK,EAAE,UAAU,EAAE,KAAK,GAAI,CAAA;AAC3D,CAAC,CAAC,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4NG;AACH,MAAM,wBAAwB,GAAG,KAAK,CAAC,IAAI,CAAC,SAAS,wBAAwB,CAAC,EAC5E,IAAI,EACJ,iBAAiB,EACjB,eAAe,EACf,GAAG,KAAK,EAQT;IACC,MAAM,CAAC,EAAE,UAAU,EAAE,UAAU,EAAE,kBAAkB,EAAE,EAAE,iBAAiB,CAAC,GACvE,sBAAsB,CAAC,IAAI,EAAE,iBAAiB,EAAE,eAAe,CAAC,CAAA;IAClE,OAAO,CACL,oBAAC,gBAAgB,OACX,KAAK,EACT,UAAU,EAAE,KAAK,EACjB,UAAU,EAAE,UAAU,EACtB,UAAU,EAAE,UAAU,EACtB,iBAAiB,EAAE,iBAAiB,EACpC,kBAAkB,EAAE,kBAAkB,GACtC,CACH,CAAA;AACH,CAAC,CAAC,CAAA;AAEF,OAAO,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,CAAA","sourcesContent":["import * as React from 'react'\nimport { FormTypes, SubmissionTypes } from '@oneblink/types'\nimport OneBlinkFormBase, {\n  OneBlinkFormBaseProps,\n  OneBlinkFormControlledProps,\n} from './OneBlinkFormBase'\nimport useFormSubmissionState from './hooks/useFormSubmissionState'\n\nexport { OneBlinkFormBaseProps, OneBlinkFormControlledProps }\n\n/**\n * Similar to {@link OneBlinkForm}, however requires props to control the\n * `definition` and `submission` values.\n *\n * #### Example\n *\n * ```tsx\n * import React from 'react'\n * import ReactDOM from 'react-dom'\n * import { FormTypes } from '@oneblink/types'\n * import {\n *   OneBlinkAppsError,\n *   draftService,\n *   submissionService,\n * } from '@oneblink/apps'\n * import {\n *   IsOfflineContextProvider,\n *   OneBlinkFormControlled,\n *   useIsMounted,\n *   useFormSubmissionState,\n * } from '@oneblink/apps-react'\n * import '@oneblink/apps-react/dist/styles.css'\n *\n * const captchaSiteKey = 'ENTER_YOUR_SITE_KEY_HERE'\n * const googleMapsApiKey = 'ENTER_YOUR_MAPS_API_KEY_HERE'\n * const formsAppId = 1\n * const form: FormTypes.Form = {\n *   id: 1,\n *   name: 'Name of Form',\n *   description: '',\n *   organisationId: 'abc123',\n *   formsAppEnvironmentId: 1,\n *   formsAppIds: [],\n *   elements: [],\n *   isAuthenticated: false,\n *   isMultiPage: false,\n *   isInfoPage: false,\n *   publishStartDate: null,\n *   publishEndDate: null,\n *   postSubmissionAction: 'FORMS_LIBRARY',\n *   submissionEvents: [],\n *   tags: [],\n * }\n * const initialSubmission: Record<string, unknown> = {\n *   data: 1,\n * }\n *\n * function FormContainer() {\n *   const isMounted = useIsMounted()\n *\n *   const [{ definition, submission }, setFormSubmission] =\n *     useFormSubmissionState(form, initialSubmission)\n *\n *   const [{ isSavingDraft, saveDraftError }, setSaveDraftState] =\n *     React.useState({\n *       isSavingDraft: false,\n *       saveDraftError: null,\n *     })\n *\n *   const [\n *     { isSubmitting, submitError, formSubmissionResult },\n *     setSubmitState,\n *   ] = React.useState({\n *     formSubmissionResult: null,\n *     isSubmitting: false,\n *     submitError: null,\n *   })\n *\n *   const handleSubmit = React.useCallback(\n *     async (newFormSubmission: FormTypes.NewFormSubmission) => {\n *       const formSubmission: FormSubmission = Object.assign(\n *         {},\n *         newFormSubmission,\n *         {\n *           formsAppId,\n *           jobId: null,\n *           externalId: null,\n *           draftId: null,\n *           preFillFormDataId: null,\n *         },\n *       )\n *\n *       setSubmitState({\n *         formSubmissionResult: null,\n *         submitError: null,\n *         isSubmitting: true,\n *       })\n *\n *       try {\n *         const newFormSubmissionResult = await submissionService.submit({\n *           formSubmission,\n *         })\n *         if (\n *           newFormSubmissionResult.isOffline &&\n *           !newFormSubmissionResult.isInPendingQueue\n *         ) {\n *           throw new OneBlinkAppsError(\n *             'You cannot submit this form while offline, please try again when connectivity is restored.',\n *             {\n *               isOffline: true,\n *             },\n *           )\n *         }\n *\n *         if (isMounted.current) {\n *           setSubmitState({\n *             formSubmissionResult: newFormSubmissionResult,\n *             isSubmitting: false,\n *             submitError: null,\n *           })\n *         }\n *       } catch (error) {\n *         if (isMounted.current) {\n *           setSubmitState({\n *             formSubmissionResult: null,\n *             isSubmitting: false,\n *             submitError: error,\n *           })\n *         }\n *       }\n *     },\n *     [isMounted],\n *   )\n *\n *   const handleSaveDraft = React.useCallback(\n *     async (newDraftSubmission: FormTypes.NewDraftSubmission) => {\n *       const draftSubmission: FormTypes.DraftSubmission = {\n *         ...newDraftSubmission,\n *         formsAppId,\n *       }\n *       setSaveDraftState({\n *         saveDraftError: null,\n *         isSavingDraft: true,\n *       })\n *\n *       try {\n *         await draftService.addDraft(\n *           {\n *             title: form.name,\n *             formId: form.id,\n *             externalId: null,\n *             jobId: null,\n *           },\n *           draftSubmission,\n *         )\n *\n *         if (isMounted.current) {\n *           setSaveDraftState({\n *             saveDraftError: null,\n *             isSavingDraft: false,\n *           })\n *         }\n *       } catch (error) {\n *         if (isMounted.current) {\n *           setSaveDraftState({\n *             saveDraftError: error,\n *             isSavingDraft: false,\n *           })\n *         }\n *       }\n *     },\n *     [isMounted],\n *   )\n *\n *   const handleCancel = React.useCallback(() => {\n *     // handle cancel here...\n *   }, [])\n *\n *   if (isSubmitting) {\n *     // Render submitting animation/loading\n *   }\n *\n *   if (submitError) {\n *     // Render error while submitting\n *   }\n *\n *   if (isSavingDraft) {\n *     // Render saving draft animation/loading\n *   }\n *\n *   if (saveDraftError) {\n *     // Render error while saving draft\n *   }\n *\n *   if (formSubmissionResult) {\n *     // Render submission success\n *   }\n *\n *   return (\n *     <OneBlinkFormControlled\n *       captchaSiteKey={captchaSiteKey}\n *       googleMapsApiKey={googleMapsApiKey}\n *       formsAppId={formsAppId}\n *       definition={definition}\n *       submission={submission}\n *       setFormSubmission={setFormSubmission}\n *       onCancel={handleCancel}\n *       onSubmit={handleSubmit}\n *       onSaveDraft={handleSaveDraft}\n *     />\n *   )\n * }\n *\n * function App() {\n *   return (\n *     <IsOfflineContextProvider>\n *       <FormContainer />\n *     </IsOfflineContextProvider>\n *   )\n * }\n *\n * const root = document.getElementById('root')\n * if (root) {\n *   ReactDOM.render(<App />, root)\n * }\n * ```\n *\n * #### Implementing Controlled Auto Save\n *\n * The {@link OneBlinkAutoSaveForm} component does not offer props to allow for a\n * controlled form (i.e. having access to `submission` and `definition` values).\n * To implement a controlled version of the `<OneBlinkAutoSaveForm />`\n * component, use the example component below.\n *\n * ```tsx\n * import * as React from 'react'\n * import {\n *   OneBlinkAutoSaveForm,\n *   OneBlinkFormControlled,\n *   useFormSubmissionAutoSaveState,\n * } from '@oneblink/apps-react'\n *\n * function OneBlinkAutoSaveFormControlled({\n *   form,\n *   initialSubmission,\n *   autoSaveKey,\n *   onCancel,\n *   onSubmit,\n *   onSaveDraft,\n *   ...props\n * }: React.ComponentProps<typeof OneBlinkAutoSaveForm>) {\n *   const {\n *     definition,\n *     submission,\n *     isLoadingAutoSaveSubmission,\n *     isAutoSaveSubmissionAvailable,\n *     startNewSubmission,\n *     continueAutoSaveSubmission,\n *     handleSubmit,\n *     handleCancel,\n *     handleSaveDraft,\n *     setFormSubmission,\n *   } = useFormSubmissionAutoSaveState({\n *     form,\n *     initialSubmission,\n *     autoSaveKey,\n *     onCancel,\n *     onSubmit,\n *     onSaveDraft,\n *   })\n *\n *   // This is just an example of how you could intercept\n *   // the change event when a user enters/selects a value\n *   // on the form.\n *   const customSetFormSubmission = React.useCallback(\n *     (formSubmission) => {\n *       setFormSubmission((currentFormSubmission) => {\n *         const newFormSubmission =\n *           typeof formSubmission === 'function'\n *             ? formSubmission(currentFormSubmission)\n *             : formSubmission\n *\n *         // This is where you can access the updated\n *         // submission data or form definition.\n *         // You could even change the form definition\n *         // programmatically based on user inputs.\n *         console.log(\n *           'A change has occurred to the submission',\n *           newFormSubmission.submission,\n *         )\n *         newFormSubmission.definition.isInfoPage =\n *           !newFormSubmission.submission.doesTheUserNeedToSubmit\n *\n *         return newFormSubmission\n *       })\n *     },\n *     [setFormSubmission],\n *   )\n *\n *   if (isLoadingAutoSaveSubmission) {\n *     return <p>Checking for auto save data...</p>\n *   }\n *\n *   if (isAutoSaveSubmissionAvailable) {\n *     return (\n *       <>\n *         <p>Do you want to use the auto save data?</p>\n *         <button onClick={startNewSubmission}>No, start again</button>\n *         <button onClick={continueAutoSaveSubmission}>\n *           Yes, continue\n *         </button>\n *       </>\n *     )\n *   }\n *\n *   return (\n *     <OneBlinkFormControlled\n *       {...props}\n *       submission={submission}\n *       definition={definition}\n *       onCancel={handleCancel}\n *       onSubmit={handleSubmit}\n *       onSaveDraft={handleSaveDraft}\n *       setFormSubmission={customSetFormSubmission}\n *     />\n *   )\n * }\n *\n * export default React.memo(OneBlinkAutoSaveFormControlled)\n * ```\n *\n * @param props\n * @returns\n * @group Components\n */\nconst OneBlinkFormControlled = React.memo(function OneBlinkFormControlled(\n  props: OneBlinkFormBaseProps & OneBlinkFormControlledProps,\n) {\n  return <OneBlinkFormBase {...props} isReadOnly={false} />\n})\n\n/**\n * Component for rendering a OneBlink Form. This component will render the\n * submit, cancel and save draft buttons but it is up to the developer to\n * implement what happens when those buttons are clicked.\n *\n * It is also recommended to import the `css` from this library as well.\n *\n * ```js\n * import { OneBlinkForm } from '@oneblink/apps-react'\n * import '@oneblink/apps-react/dist/styles.css'\n * ```\n *\n * #### Example\n *\n * ```tsx\n * import React from 'react'\n * import ReactDOM from 'react-dom'\n * import { FormTypes } from '@oneblink/types'\n * import {\n *   OneBlinkAppsError,\n *   draftService,\n *   submissionService,\n * } from '@oneblink/apps'\n * import {\n *   IsOfflineContextProvider,\n *   OneBlinkForm,\n *   useIsMounted,\n * } from '@oneblink/apps-react'\n * import '@oneblink/apps-react/dist/styles.css'\n *\n * const captchaSiteKey = 'ENTER_YOUR_SITE_KEY_HERE'\n * const googleMapsApiKey = 'ENTER_YOUR_MAPS_API_KEY_HERE'\n * const formsAppId = 1\n * const form: FormTypes.Form = {\n *   id: 1,\n *   name: 'Name of Form',\n *   description: '',\n *   organisationId: 'abc123',\n *   formsAppEnvironmentId: 1,\n *   formsAppIds: [],\n *   elements: [],\n *   isAuthenticated: false,\n *   isMultiPage: false,\n *   isInfoPage: false,\n *   publishStartDate: null,\n *   publishEndDate: null,\n *   postSubmissionAction: 'FORMS_LIBRARY',\n *   submissionEvents: [],\n *   tags: [],\n * }\n *\n * function FormContainer() {\n *   const isMounted = useIsMounted()\n *\n *   const [{ isSavingDraft, saveDraftError }, setSaveDraftState] =\n *     React.useState({\n *       isSavingDraft: false,\n *       saveDraftError: null,\n *     })\n *\n *   const [\n *     { isSubmitting, submitError, formSubmissionResult },\n *     setSubmitState,\n *   ] = React.useState({\n *     formSubmissionResult: null,\n *     isSubmitting: false,\n *     submitError: null,\n *   })\n *\n *   const handleSubmit = React.useCallback(\n *     async (newFormSubmission: FormTypes.NewFormSubmission) => {\n *       const formSubmission: FormSubmission = Object.assign(\n *         {},\n *         newFormSubmission,\n *         {\n *           formsAppId,\n *           jobId: null,\n *           externalId: null,\n *           draftId: null,\n *           preFillFormDataId: null,\n *         },\n *       )\n *\n *       setSubmitState({\n *         formSubmissionResult: null,\n *         submitError: null,\n *         isSubmitting: true,\n *       })\n *\n *       try {\n *         const newFormSubmissionResult = await submissionService.submit({\n *           formSubmission,\n *         })\n *         if (\n *           newFormSubmissionResult.isOffline &&\n *           !newFormSubmissionResult.isInPendingQueue\n *         ) {\n *           throw new OneBlinkAppsError(\n *             'You cannot submit this form while offline, please try again when connectivity is restored.',\n *             {\n *               isOffline: true,\n *             },\n *           )\n *         }\n *\n *         if (isMounted.current) {\n *           setSubmitState({\n *             formSubmissionResult: newFormSubmissionResult,\n *             isSubmitting: false,\n *             submitError: null,\n *           })\n *         }\n *       } catch (error) {\n *         if (isMounted.current) {\n *           setSubmitState({\n *             formSubmissionResult: null,\n *             isSubmitting: false,\n *             submitError: error,\n *           })\n *         }\n *       }\n *     },\n *     [isMounted],\n *   )\n *\n *   const handleSaveDraft = React.useCallback(\n *     async (newDraftSubmission: FormTypes.NewDraftSubmission) => {\n *       const draftSubmission: FormTypes.DraftSubmission = {\n *         ...newDraftSubmission,\n *         formsAppId,\n *       }\n *       setSaveDraftState({\n *         saveDraftError: null,\n *         isSavingDraft: true,\n *       })\n *\n *       try {\n *         await draftService.addDraft(\n *           {\n *             title: form.name,\n *             formId: form.id,\n *             externalId: null,\n *             jobId: null,\n *           },\n *           draftSubmission,\n *         )\n *\n *         if (isMounted.current) {\n *           setSaveDraftState({\n *             saveDraftError: null,\n *             isSavingDraft: false,\n *           })\n *         }\n *       } catch (error) {\n *         if (isMounted.current) {\n *           setSaveDraftState({\n *             saveDraftError: error,\n *             isSavingDraft: false,\n *           })\n *         }\n *       }\n *     },\n *     [isMounted],\n *   )\n *\n *   const handleCancel = React.useCallback(() => {\n *     // handle cancel here...\n *   }, [isMounted])\n *\n *   if (isSubmitting) {\n *     // Render submitting animation/loading\n *   }\n *\n *   if (submitError) {\n *     // Render error while submitting\n *   }\n *\n *   if (isSavingDraft) {\n *     // Render saving draft animation/loading\n *   }\n *\n *   if (saveDraftError) {\n *     // Render error while saving draft\n *   }\n *\n *   if (formSubmissionResult) {\n *     // Render submission success\n *   }\n *\n *   return (\n *     <OneBlinkForm\n *       captchaSiteKey={captchaSiteKey}\n *       googleMapsApiKey={googleMapsApiKey}\n *       formsAppId={formsAppId}\n *       form={form}\n *       onCancel={handleCancel}\n *       onSubmit={handleSubmit}\n *       onSaveDraft={handleSaveDraft}\n *       attachmentRetentionInDays={1}\n *     />\n *   )\n * }\n *\n * function App() {\n *   return (\n *     <IsOfflineContextProvider>\n *       <FormContainer />\n *     </IsOfflineContextProvider>\n *   )\n * }\n *\n * const root = document.getElementById('root')\n * if (root) {\n *   ReactDOM.render(<App />, root)\n * }\n * ```\n *\n * @param props\n * @returns\n * @group Components\n */\nconst OneBlinkFormUncontrolled = React.memo(function OneBlinkFormUncontrolled({\n  form,\n  initialSubmission,\n  resumeAtElement,\n  ...props\n}: OneBlinkFormBaseProps & {\n  /** The OneBlink Form to render */\n  form: FormTypes.Form\n  /** The initial submission data */\n  initialSubmission?: SubmissionTypes.S3SubmissionData['submission']\n  /** The element to resume the form at. */\n  resumeAtElement?: FormTypes.FormElement\n}) {\n  const [{ definition, submission, lastElementUpdated }, setFormSubmission] =\n    useFormSubmissionState(form, initialSubmission, resumeAtElement)\n  return (\n    <OneBlinkFormBase\n      {...props}\n      isReadOnly={false}\n      definition={definition}\n      submission={submission}\n      setFormSubmission={setFormSubmission}\n      lastElementUpdated={lastElementUpdated}\n    />\n  )\n})\n\nexport { OneBlinkFormControlled, OneBlinkFormUncontrolled }\n"]}

package/dist/OneBlinkFormBase.d.ts

@@ -1,32 +1,77 @@
 import * as React from 'react';
 import { submissionService } from '@oneblink/apps';
-import { FormTypes, FormsAppsTypes } from '@oneblink/types';
-import { FormSubmissionModel, SetFormSubmission } from './types/form';
-export type BaseProps = {
+import { FormTypes, FormsAppsTypes, SubmissionTypes } from '@oneblink/types';
+import { SetFormSubmission } from './types/form';
+export type OneBlinkFormBaseProps = {
+    /** The function to call when the user cancels the form */
     onCancel: () => unknown;
+    /**
+     * The function to call when the user submits the form with valid submission
+     * data. See
+     * [NewFormSubmission](https://oneblink.github.io/apps/modules/submissionService.html#NewFormSubmission)
+     * for the structure of the argument.
+     */
     onSubmit: (newFormSubmission: submissionService.NewFormSubmission) => unknown;
+    /** Whether the form is currently able to be submitted. False by default. */
     disabled?: boolean;
     isPreview?: boolean;
+    /**
+     * A [Google Maps API
+     * Key](https://developers.google.com/maps/documentation/javascript/get-api-key).
+     * Required if the form contains a `location` form element.
+     */
     googleMapsApiKey?: string;
+    /**
+     * An [ABN Lookup Authentication
+     * Guid](https://abr.business.gov.au/Tools/WebServices). Required if the form
+     * contains a `abn` form element.
+     */
     abnLookupAuthenticationGuid?: string;
+    /**
+     * A [reCAPTCHA Site Key](https://developers.google.com/recaptcha/intro).
+     * Required if the form contains a `captcha` form element.
+     */
     captchaSiteKey?: string;
+    /** Change properties for certain buttons on the form. */
     buttons?: FormsAppsTypes.FormsListStyles['buttons'];
+    /** Hex colour value for certain inputs (defaults to `#4c8da7`). */
     primaryColour?: string;
+    /** Number of days attachments are retained for. */
     attachmentRetentionInDays?: number;
-    allowSubmitWithPendingAttachments?: boolean;
+    /**
+     * If set to `false`, submission will be prevented while offline. If set to
+     * `true`, the user will be prompted to allow them to continue with
+     * attachments uploading in the background later.
+     */
+    isPendingQueueEnabled: boolean;
+    /**
+     * The function to call when the user wishes to save there submission data as
+     * a draft submission. If not specified, drafts cannot be saved. See
+     * [NewDraftSubmission](https://oneblink.github.io/apps/modules/submissionService.html#NewDraftSubmission)
+     * for the structure of the argument.
+     */
     onSaveDraft?: (newDraftSubmission: submissionService.NewDraftSubmission) => unknown;
+    /**
+     * The function to call when the user needs to navigate away from the form.
+     * e.g. `history.push`
+     */
     handleNavigateAway?: () => unknown;
+    /**
+     * Determines whether the form is submittable or not. Info page type forms
+     * show a "Done" button instead of a "Submit" button. Defaults to
+     * "CALCULATED"
+     */
     isInfoPage?: 'YES' | 'NO' | 'CALCULATED';
 };
-export type ControlledProps = {
+export type OneBlinkFormControlledProps = {
     definition: FormTypes.Form;
-    submission: FormSubmissionModel;
+    submission: SubmissionTypes.S3SubmissionData['submission'];
     setFormSubmission: SetFormSubmission;
     lastElementUpdated?: FormTypes.FormElement;
 };
-type Props = BaseProps & ControlledProps & {
+type Props = OneBlinkFormBaseProps & OneBlinkFormControlledProps & {
     isReadOnly: boolean;
 };
-declare function OneBlinkFormBase({ googleMapsApiKey, abnLookupAuthenticationGuid, captchaSiteKey, definition, disabled, isPreview, submission, isReadOnly, onCancel, onSubmit, onSaveDraft, setFormSubmission, buttons, primaryColour, attachmentRetentionInDays, allowSubmitWithPendingAttachments, handleNavigateAway, isInfoPage: isInfoPageProp, lastElementUpdated, }: Props): JSX.Element;
+declare function OneBlinkFormBase({ googleMapsApiKey, abnLookupAuthenticationGuid, captchaSiteKey, definition, disabled, isPreview, submission, isReadOnly, onCancel, onSubmit, onSaveDraft, setFormSubmission, buttons, primaryColour, attachmentRetentionInDays, isPendingQueueEnabled, handleNavigateAway, isInfoPage: isInfoPageProp, lastElementUpdated, }: Props): JSX.Element;
 declare const _default: React.MemoExoticComponent<typeof OneBlinkFormBase>;
 export default _default;