web-forms (Vue UI): quick & dirty reset demo state on “submit”, “restore” state

eyelidlessness · eyelidlessness · commit 3dfd7d97acf7 · 2025-03-03T15:30:29.000-08:00
This definitely needs refinement if we’re going to keep it. I felt it was valuable at this stage in the engine/client interface evolution to integrate the following to see the behavior in action:

- Load form state independent of instance
  - Still create instance on load
- On “submit”
  - Create a new instance (resets form state immediately)
  - Simulate an “offline queue”-like experience, storing “submitted” instance payloads in a list where they can be:
    - Removed individually
    - Cleared completely
    - **RESTORED** from their payload state

The latter isn’t fully working in the engine yet, but the engine/client interface is far enough along that this integration should demonstrate it once it is!
diff --git a/packages/web-forms/src/components/OdkWebForm.vue b/packages/web-forms/src/components/OdkWebForm.vue
@@ -1,17 +1,21 @@
 <script setup lang="ts">
+import {
+	initializeFormResultState,
+	initializeInstanceState,
+	instanceState,
+} from '@/shared-state/form-state.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 { computed, getCurrentInstance, provide, ref, watchEffect } from 'vue';
 import { FormInitializationError } from '../lib/error/FormInitializationError.ts';
 import FormLoadFailureDialog from './Form/FormLoadFailureDialog.vue';
 import FormHeader from './FormHeader.vue';
@@ -105,14 +109,15 @@ const emitSubmitChunked = async (root: RootNode) => {
 
 const emit = defineEmits<OdkWebFormEmits>();
 
-const odkForm = ref<RootNode>();
+const odkForm = computed(() => instanceState.value?.root);
+
 const submitPressed = ref(false);
 const initializeFormError = ref<FormInitializationError | null>();
 
 const init = async () => {
 	const { formXml, fetchFormAttachment, missingResourceBehavior } = props;
 
-	const formResult = await loadForm(formXml, {
+	const formResult = await initializeFormResultState(formXml, {
 		fetchFormAttachment,
 		missingResourceBehavior,
 	});
@@ -124,9 +129,7 @@ const init = async () => {
 	}
 
 	try {
-		const { root } = formResult.createInstance({ stateFactory: reactive });
-
-		odkForm.value = root;
+		initializeInstanceState(formResult);
 	} catch (error) {
 		initializeFormError.value = FormInitializationError.from(error);
 	}
diff --git a/packages/web-forms/src/demo/FormPreview.vue b/packages/web-forms/src/demo/FormPreview.vue
@@ -1,4 +1,5 @@
 <script setup lang="ts">
+import { resetInstanceState } from '@/shared-state/form-state.ts';
 import { xformFixturesByCategory, XFormResource } from '@getodk/common/fixtures/xforms.ts';
 import type {
 	ChunkedInstancePayload,
@@ -10,7 +11,9 @@ import { constants as ENGINE_CONSTANTS } from '@getodk/xforms-engine';
 import { ref } from 'vue';
 import { useRoute } from 'vue-router';
 import OdkWebForm from '../components/OdkWebForm.vue';
+import { cacheInstance } from '../shared-state/instance-cache-state.ts';
 import FeedbackButton from './FeedbackButton.vue';
+import InstanceCache from './InstanceCache.vue';
 
 const route = useRoute();
 
@@ -59,7 +62,8 @@ const handleSubmit = (payload: MonolithicInstancePayload) => {
 	// eslint-disable-next-line no-console
 	console.log('submission payload:', payload);
 
-	alert(`Submit button was pressed`);
+	cacheInstance(payload);
+	resetInstanceState();
 };
 
 const handleSubmitChunked = (payload: ChunkedInstancePayload) => {
@@ -69,6 +73,7 @@ const handleSubmitChunked = (payload: ChunkedInstancePayload) => {
 </script>
 <template>
 	<template v-if="formPreviewState">
+		<InstanceCache />
 		<OdkWebForm
 			:form-xml="formPreviewState.formXML"
 			:fetch-form-attachment="formPreviewState.fetchFormAttachment"
diff --git a/packages/web-forms/src/demo/InstanceCache.vue b/packages/web-forms/src/demo/InstanceCache.vue
@@ -0,0 +1,137 @@
+<script setup lang="ts">
+import PrimeButton from 'primevue/button';
+import type { AnyInstance, InstantiableFormResult } from '../shared-state/form-state.ts';
+import { instantiableFormResult, restoreInstanceState } from '../shared-state/form-state.ts';
+import type { InstanceCacheItem } from '../shared-state/instance-cache-state.ts';
+import {
+	clearCache,
+	evictCachedInstance,
+	instanceCache,
+} from '../shared-state/instance-cache-state.ts';
+
+const formatTimeUnit = (timeUnit: number): string => {
+	return timeUnit.toString().padStart(2, '0');
+};
+
+const formatTimestamp = (date: Date): string => {
+	const hours = date.getHours();
+	const minutes = date.getMinutes();
+	const seconds = date.getSeconds();
+
+	return [hours, minutes, seconds].map(formatTimeUnit).join(':');
+};
+
+const restoreCacheItem = async (
+	formResult: InstantiableFormResult,
+	item: InstanceCacheItem
+): Promise<AnyInstance> => {
+	const instance = await restoreInstanceState(formResult, item.payload);
+
+	evictCachedInstance(item);
+
+	return instance;
+};
+</script>
+
+<template>
+	<section v-if="instantiableFormResult" class="demo-instance-cache">
+		<details>
+			<summary>Instance cache</summary>
+
+			<p>This is an in-memory demo simulating storage and restoration of instance state, which might be similar to the experience of a Web Forms offline mode.</p>
+
+			<template v-if="instanceCache.items.length > 0">
+				<div class="cache-header flex">
+					<span>Cached instances ({{ instanceCache.items.length }})</span>
+
+					<PrimeButton
+						text
+						@click="clearCache()"
+					>
+						Clear
+					</PrimeButton>
+				</div>
+
+				<ul class="items">
+					<li v-for="item in instanceCache.items" :key="item.cacheTimestamp.getDate()">
+						<div class="item-row flex">
+							<PrimeButton
+								title="Remove from cache"
+								class="remove-item"
+								@click="evictCachedInstance(item)"
+							>
+								✕
+							</PrimeButton>
+
+							<div class="item-description">
+								Instance cached at {{ formatTimestamp(item.cacheTimestamp) }}
+							</div>
+
+							<PrimeButton class="restore-item" @click="restoreCacheItem(instantiableFormResult, item)">
+								Restore instance
+							</PrimeButton>
+						</div>
+					</li>
+				</ul>
+			</template>
+			<template v-else>
+				<p class="cache-empty">
+					Cache is empty!
+				</p>
+			</template>
+		</details>
+	</section>
+</template>
+
+<style scoped lang="scss">
+.demo-instance-cache {
+	padding: 1rem;
+	background-color: var(--surface-0);
+}
+
+summary {
+	cursor: pointer;
+}
+
+.flex {
+	display: flex;
+	gap: 0.5rem;
+	align-items: center;
+}
+
+.cache-empty {
+	font-size: 0.85rem;
+}
+
+.cache-header {
+	justify-content: space-between;
+}
+
+.items,
+.items li {
+	display: block;
+	list-style: none;
+}
+
+.items {
+	margin: 0;
+	padding: 0;
+}
+
+.items li {
+	margin: 0;
+	padding: 0.25rem;
+}
+
+.item-description {
+	flex-grow: 1;
+}
+
+.remove-item {
+	display: block;
+	width: 1.5rem;
+	min-width: 0;
+	height: 1.5rem;
+	padding: 0;
+}
+</style>
diff --git a/packages/web-forms/src/shared-state/form-state.ts b/packages/web-forms/src/shared-state/form-state.ts
@@ -0,0 +1,112 @@
+import type {
+	CreatedFormInstance,
+	FormInstanceConfig,
+	LoadFormOptions,
+	LoadFormResult,
+	LoadFormSuccessResult,
+	LoadFormWarningResult,
+	RestoredFormInstance,
+} from '@getodk/xforms-engine';
+import { loadForm } from '@getodk/xforms-engine';
+import type { Ref } from 'vue';
+import { computed, reactive, ref } from 'vue';
+import type { AnyInstancePayload } from './instance-cache-state.ts';
+
+// prettier-ignore
+export type InstantiableFormResult =
+	| LoadFormSuccessResult
+	| LoadFormWarningResult;
+
+export const formResultState: Ref<LoadFormResult | null> = ref(null);
+
+const isInstantiableFormResult = (
+	formResult: LoadFormResult | null
+): formResult is InstantiableFormResult => {
+	return formResult != null && formResult.status !== 'failure';
+};
+
+export const instantiableFormResult = computed(() => {
+	const formResult = formResultState.value;
+
+	if (isInstantiableFormResult(formResult)) {
+		return formResult;
+	}
+
+	return null;
+});
+
+export const initializeFormResultState = async (
+	formXML: string,
+	options: LoadFormOptions
+): Promise<LoadFormResult> => {
+	const formResult = await loadForm(formXML, options);
+
+	formResultState.value = formResult;
+
+	return formResult;
+};
+
+const instanceConfig: FormInstanceConfig = {
+	stateFactory: reactive,
+};
+
+// prettier-ignore
+export type AnyInstance =
+	| CreatedFormInstance
+	| RestoredFormInstance;
+
+export const instanceState: Ref<AnyInstance | null> = ref(null);
+
+export const initializeInstanceState = (
+	formResult: InstantiableFormResult
+): CreatedFormInstance => {
+	const instance = formResult.createInstance(instanceConfig);
+
+	instanceState.value = instance;
+
+	return instanceState.value;
+};
+
+interface FormInstanceState {
+	readonly formResult: LoadFormResult;
+	readonly instance: AnyInstance;
+}
+
+export const initializeFormInstanceState = async (
+	formXML: string,
+	options: LoadFormOptions
+): Promise<FormInstanceState | null> => {
+	const formResult = await initializeFormResultState(formXML, options);
+
+	if (formResult.status === 'failure') {
+		instanceState.value = null;
+
+		return null;
+	}
+
+	const instance = initializeInstanceState(formResult);
+
+	return {
+		formResult,
+		instance,
+	};
+};
+
+export const restoreInstanceState = async (
+	formResult: InstantiableFormResult,
+	payload: AnyInstancePayload
+): Promise<AnyInstance> => {
+	const instance = await formResult.restoreInstance(payload, instanceConfig);
+
+	instanceState.value = instance;
+
+	return instance;
+};
+
+export const resetInstanceState = () => {
+	const formResult = formResultState.value;
+
+	if (isInstantiableFormResult(formResult)) {
+		initializeInstanceState(formResult);
+	}
+};
diff --git a/packages/web-forms/src/shared-state/instance-cache-state.ts b/packages/web-forms/src/shared-state/instance-cache-state.ts
@@ -0,0 +1,61 @@
+import type { InstancePayload, InstancePayloadType } from '@getodk/xforms-engine';
+import type { Ref } from 'vue';
+import { inject, provide, ref } from 'vue';
+
+export type AnyInstancePayload = InstancePayload<InstancePayloadType>;
+
+export interface InstanceCacheItem {
+	readonly cacheTimestamp: Date;
+	readonly payload: AnyInstancePayload;
+}
+
+export interface InstanceCacheState {
+	readonly items: readonly InstanceCacheItem[];
+}
+
+const defaultInstanceCacheState: InstanceCacheState = {
+	items: [],
+};
+
+export const instanceCache: Ref<InstanceCacheState> =
+	ref<InstanceCacheState>(defaultInstanceCacheState);
+
+type SetItemsCallback = (items: readonly InstanceCacheItem[]) => readonly InstanceCacheItem[];
+
+const setItems = (callback: SetItemsCallback): InstanceCacheState => {
+	const current = instanceCache.value.items;
+
+	instanceCache.value = {
+		items: callback(current),
+	};
+
+	return instanceCache.value;
+};
+
+export const cacheInstance = (payload: AnyInstancePayload): InstanceCacheState => {
+	return setItems((current) => [
+		...current,
+		{
+			cacheTimestamp: new Date(),
+			payload,
+		},
+	]);
+};
+
+export const evictCachedInstance = (instance: InstanceCacheItem): InstanceCacheState => {
+	return setItems((items) => {
+		return items.filter((item) => item !== instance);
+	});
+};
+
+export const provideInstanceCache = () => {
+	return provide<Ref<InstanceCacheState>, 'instanceCache'>('instanceCache', instanceCache);
+};
+
+export const injectInstanceCache = () => {
+	return inject<Ref<InstanceCacheState>>('instance', instanceCache);
+};
+
+export const clearCache = (): InstanceCacheState => {
+	return setItems(() => []);
+};
