Merge pull request #355 from getodk/edit-epic/host-app-integration-edit-create-n

Initial support for editing submissions, resetting form state after submission

Author: eyelidlessness

.changeset/lemon-pumpkins-smile.md

@@ -0,0 +1,5 @@
+---
+'@getodk/web-forms': minor
+---
+
+Support resetting form state after submission

.changeset/silly-candles-battle.md

@@ -0,0 +1,5 @@
+---
+'@getodk/web-forms': minor
+---
+
+Support for editing submissions

packages/web-forms/src/components/OdkWebForm.vue

@@ -1,42 +1,73 @@
 <script setup lang="ts">
+import type { FormStateSuccessResult } from '@/lib/init/FormState.ts';
+import { initializeFormState } from '@/lib/init/initializeFormState.ts';
+import type { EditInstanceOptions } from '@/lib/init/loadFormState';
+import { loadFormState } from '@/lib/init/loadFormState';
+import { updateSubmittedFormState } from '@/lib/init/updateSubmittedFormState.ts';
+import type {
+	HostSubmissionResultCallback,
+	OptionalAwaitableHostSubmissionResult,
+} from '@/lib/submission/HostSubmissionResultCallback.ts';
 import type {
 	ChunkedInstancePayload,
 	FetchFormAttachment,
 	MissingResourceBehavior,
 	MonolithicInstancePayload,
-	RootNode,
 } from '@getodk/xforms-engine';
-import { loadForm } from '@getodk/xforms-engine';
 import Button from 'primevue/button';
 import Card from 'primevue/card';
 import PrimeMessage from 'primevue/message';
 import type { ComponentPublicInstance } from 'vue';
-import { computed, getCurrentInstance, provide, reactive, ref, watchEffect } from 'vue';
-import { FormInitializationError } from '../lib/error/FormInitializationError.ts';
+import { computed, getCurrentInstance, provide, ref, watchEffect } from 'vue';
 import FormLoadFailureDialog from './Form/FormLoadFailureDialog.vue';
 import FormHeader from './FormHeader.vue';
 import QuestionList from './QuestionList.vue';
 
 const webFormsVersion = __WEB_FORMS_VERSION__;
 
-interface OdkWebFormsProps {
-	formXml: string;
-	fetchFormAttachment: FetchFormAttachment;
-	missingResourceBehavior?: MissingResourceBehavior;
+export interface OdkWebFormsProps {
+	readonly formXml: string;
+	readonly fetchFormAttachment: FetchFormAttachment;
+	readonly missingResourceBehavior?: MissingResourceBehavior;
 
 	/**
 	 * Note: this parameter must be set when subscribing to the
 	 * {@link OdkWebFormEmits.submitChunked | submitChunked} event.
 	 */
-	submissionMaxSize?: number;
+	readonly submissionMaxSize?: number;
+
+	/**
+	 * If provided by a host application, referenced instance and attachment
+	 * resources will be resolved and loaded for editing.
+	 */
+	readonly editInstance?: EditInstanceOptions;
 }
 
 const props = defineProps<OdkWebFormsProps>();
 
+const hostSubmissionResultCallbackFactory = (
+	currentState: FormStateSuccessResult
+): HostSubmissionResultCallback => {
+	const handleHostSubmissionResult = async (
+		hostResult: OptionalAwaitableHostSubmissionResult
+	): Promise<void> => {
+		const submissionResult = await hostResult;
+
+		state.value = updateSubmittedFormState(submissionResult, currentState);
+	};
+
+	return (hostResult) => {
+		void handleHostSubmissionResult(hostResult);
+	};
+};
+
 // eslint-disable-next-line @typescript-eslint/consistent-type-definitions -- evidently a type must be used for this to be assigned to a name (which we use!); as an interface, it won't satisfy the `Record` constraint of `defineEmits`.
 type OdkWebFormEmits = {
-	submit: [submissionPayload: MonolithicInstancePayload];
-	submitChunked: [submissionPayload: ChunkedInstancePayload];
+	submit: [submissionPayload: MonolithicInstancePayload, callback: HostSubmissionResultCallback];
+	submitChunked: [
+		submissionPayload: ChunkedInstancePayload,
+		callback: HostSubmissionResultCallback,
+	];
 };
 
 /**
@@ -50,7 +81,7 @@ type OdkWebFormEmits = {
  * {@link computed} function body (or any function body), but produces the
  * expected value assigned to a top level value as it is here.
  */
-const instance = getCurrentInstance();
+const componentInstance = getCurrentInstance();
 
 type OdkWebFormEmitsEventType = keyof OdkWebFormEmits;
 
@@ -69,79 +100,67 @@ type EventKey = `on${Capitalize<OdkWebFormEmitsEventType>}`;
 
 /**
  * @see {@link https://mokkapps.de/vue-tips/check-if-component-has-event-listener-attached}
- * @see {@link instance}
+ * @see {@link componentInstance}
  * @see {@link EventKey}
  */
 const isEmitSubscribed = (eventKey: EventKey): boolean => {
-	return eventKey in (instance?.vnode.props ?? {});
+	return eventKey in (componentInstance?.vnode.props ?? {});
 };
 
-const emitSubmit = async (root: RootNode) => {
+const emitSubmit = async (currentState: FormStateSuccessResult) => {
 	if (isEmitSubscribed('onSubmit')) {
-		const payload = await root.prepareInstancePayload({
+		const payload = await currentState.root.prepareInstancePayload({
 			payloadType: 'monolithic',
 		});
+		const callback = hostSubmissionResultCallbackFactory(currentState);
 
-		emit('submit', payload);
+		emit('submit', payload, callback);
 	}
 };
 
-const emitSubmitChunked = async (root: RootNode) => {
+const emitSubmitChunked = async (currentState: FormStateSuccessResult) => {
 	if (isEmitSubscribed('onSubmitChunked')) {
 		const maxSize = props.submissionMaxSize;
 
 		if (maxSize == null) {
 			throw new Error('The `submissionMaxSize` prop is required for chunked submissions');
 		}
 
-		const payload = await root.prepareInstancePayload({
+		const payload = await currentState.root.prepareInstancePayload({
 			payloadType: 'chunked',
 			maxSize,
 		});
+		const callback = hostSubmissionResultCallbackFactory(currentState);
 
-		emit('submitChunked', payload);
+		emit('submitChunked', payload, callback);
 	}
 };
 
 const emit = defineEmits<OdkWebFormEmits>();
 
-const odkForm = ref<RootNode>();
+const state = initializeFormState();
 const submitPressed = ref(false);
-const initializeFormError = ref<FormInitializationError | null>();
 
 const init = async () => {
-	const { formXml, fetchFormAttachment, missingResourceBehavior } = props;
-
-	const formResult = await loadForm(formXml, {
-		fetchFormAttachment,
-		missingResourceBehavior,
+	state.value = await loadFormState(props.formXml, {
+		form: {
+			fetchFormAttachment: props.fetchFormAttachment,
+			missingResourceBehavior: props.missingResourceBehavior,
+		},
+		editInstance: props.editInstance ?? null,
 	});
-
-	if (formResult.status === 'failure') {
-		initializeFormError.value = FormInitializationError.fromError(formResult.error);
-
-		return;
-	}
-
-	try {
-		const { root } = formResult.createInstance({ stateFactory: reactive });
-
-		odkForm.value = root;
-	} catch (error) {
-		initializeFormError.value = FormInitializationError.from(error);
-	}
 };
 
 void init();
 
-const handleSubmit = () => {
-	const root = odkForm.value;
+const handleSubmit = (currentState: FormStateSuccessResult) => {
+	const { root } = currentState;
 
-	if (root?.validationState.violations?.length === 0) {
+	if (root.validationState.violations.length === 0) {
 		// eslint-disable-next-line @typescript-eslint/no-floating-promises
-		emitSubmit(root);
+		emitSubmit(currentState);
 		// eslint-disable-next-line @typescript-eslint/no-floating-promises
-		emitSubmitChunked(root);
+		emitSubmitChunked(currentState);
 	} else {
 		submitPressed.value = true;
 		document.scrollingElement?.scrollTo(0, 0);
@@ -153,7 +172,7 @@ const validationErrorMessagePopover = ref<ComponentPublicInstance | null>(null);
 provide('submitPressed', submitPressed);
 
 const validationErrorMessage = computed(() => {
-	const violationLength = odkForm.value!.validationState.violations.length;
+	const violationLength = state.value.root?.validationState.violations.length ?? 0;
 
 	// TODO: translations
 	if (violationLength === 0) return '';
@@ -180,21 +199,21 @@ watchEffect(() => {
 	<div
 		:class="{
 			'form-initialization-status': true,
-			loading: odkForm == null && initializeFormError == null,
-			error: initializeFormError != null,
-			ready: odkForm != null,
+			loading: state.status === 'FORM_STATE_LOADING',
+			error: state.status === 'FORM_STATE_FAILURE',
+			ready: state.status === 'FORM_STATE_SUCCESS',
 		}"
 	/>
 
-	<template v-if="initializeFormError != null">
+	<template v-if="state.status === 'FORM_STATE_FAILURE'">
 		<FormLoadFailureDialog
 			severity="error"
-			:error="initializeFormError"
+			:error="state.error"
 		/>
 	</template>
 
 	<div
-		v-else-if="odkForm"
+		v-else-if="state.status === 'FORM_STATE_SUCCESS'"
 		class="odk-form"
 		:class="{ 'submit-pressed': submitPressed }"
 	>
@@ -204,21 +223,20 @@ watchEffect(() => {
 				{{ validationErrorMessage }}
 			</PrimeMessage>
 
-			<FormHeader :form="odkForm" />
+			<FormHeader :form="state.root" />
 
 			<Card class="questions-card">
 				<template #content>
 					<div class="form-questions">
 						<div class="flex flex-column gap-2">
-							<QuestionList :nodes="odkForm.currentState.children" />
+							<QuestionList :nodes="state.root.currentState.children" />
 						</div>
 					</div>
 				</template>
 			</Card>
 
 			<div class="footer flex justify-content-end flex-wrap gap-3">
-				<!-- maybe current state is in odkForm.state.something -->
-				<Button label="Send" rounded @click="handleSubmit()" />
+				<Button label="Send" rounded @click="handleSubmit(state)" />
 			</div>
 		</div>
 

packages/web-forms/src/index.ts

@@ -1,5 +1,6 @@
 import { webFormsPlugin } from './WebFormsPlugin';
 import OdkWebForm from './components/OdkWebForm.vue';
+import { POST_SUBMIT__NEW_INSTANCE } from './lib/constants/control-flow.ts';
 
 import '@fontsource/roboto/300.css';
 import './assets/css/icomoon.css';
@@ -8,4 +9,8 @@ import './themes/2024-light/theme.scss';
 // TODO/sk: Purge it - using postcss-purgecss
 import 'primeflex/primeflex.css';
 
-export { OdkWebForm, webFormsPlugin };
+/**
+ * @todo there are almost certainly types we should be exporting from the
+ * package entrypoint!
+ */
+export { OdkWebForm, POST_SUBMIT__NEW_INSTANCE, webFormsPlugin };

packages/web-forms/src/lib/constants/control-flow.ts

@@ -0,0 +1,10 @@
+/**
+ * Sentinel value, which may be used by a host application, once it has handled
+ * submission of a form instance, indicating that Web Forms should create a new
+ * instance of the currently loaded form.
+ */
+// In other words, if we get this from a host app like Central, we call
+// `form.createInstance()` and replace the current form's instance state with
+// the newly created instance.
+export const POST_SUBMIT__NEW_INSTANCE = Symbol('POST_SUBMIT__NEW_INSTANCE');
+export type POST_SUBMIT__NEW_INSTANCE = typeof POST_SUBMIT__NEW_INSTANCE;

packages/web-forms/src/lib/init/FormState.ts

@@ -0,0 +1,63 @@
+import type {
+	AnyFormInstance,
+	LoadFormSuccessResult,
+	LoadFormWarningResult,
+	RootNode,
+} from '@getodk/xforms-engine';
+import type { FormInitializationError } from '../error/FormInitializationError.ts';
+
+/**
+ * @todo We should probably export a type for this in the engine, both as a
+ * convenience and to assign a stable name to the concept (which will probably
+ * evolve when we address
+ * {@link https://github.com/getodk/web-forms/issues/202 | error conditions} as
+ * a holistic concern).
+ */
+export type InstantiableForm = LoadFormSuccessResult | LoadFormWarningResult;
+
+export type FormStateFailureStatus = 'FORM_STATE_FAILURE';
+export type FormStateLoadingStatus = 'FORM_STATE_LOADING';
+export type FormStateSuccessStatus = 'FORM_STATE_SUCCESS';
+
+export type FormStateStatus =
+	| FormStateFailureStatus
+	| FormStateLoadingStatus
+	| FormStateSuccessStatus;
+
+interface FormStateResult {
+	readonly status: FormStateStatus;
+	readonly error: FormInitializationError | null;
+	readonly form: InstantiableForm | null;
+	readonly instance: AnyFormInstance | null;
+	readonly root: RootNode | null;
+}
+
+export interface FormStateFailureResult extends FormStateResult {
+	readonly status: FormStateFailureStatus;
+	readonly error: FormInitializationError;
+	readonly form: null;
+	readonly instance: null;
+	readonly root: null;
+}
+
+export interface FormStateLoadingResult extends FormStateResult {
+	readonly status: FormStateLoadingStatus;
+	readonly error: null;
+	readonly form: null;
+	readonly instance: null;
+	readonly root: null;
+}
+
+export interface FormStateSuccessResult extends FormStateResult {
+	readonly status: FormStateSuccessStatus;
+	readonly error: null;
+	readonly form: InstantiableForm;
+	readonly instance: AnyFormInstance;
+	readonly root: RootNode;
+}
+
+// prettier-ignore
+export type FormState =
+	| FormStateFailureResult
+	| FormStateLoadingResult
+	| FormStateSuccessResult;

packages/web-forms/src/lib/init/engine-config.ts

@@ -0,0 +1,6 @@
+import type { FormInstanceConfig } from '@getodk/xforms-engine';
+import { reactive } from 'vue';
+
+export const ENGINE_FORM_INSTANCE_CONFIG: FormInstanceConfig = {
+	stateFactory: reactive,
+};