web-forms (Vue UI): ~minimal changes to integrate engine entrypoint revs

This leaves aside opportunities to take advantage of engine support for creating multiple instances for the same form. This is the remaining aspect of #316.

Author: eyelidlessness

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

@@ -1,10 +1,12 @@
 <script setup lang="ts">
 import type {
 	ChunkedInstancePayload,
+	FetchFormAttachment,
 	MissingResourceBehavior,
 	MonolithicInstancePayload,
+	RootNode,
 } from '@getodk/xforms-engine';
-import { initializeForm, type FetchFormAttachment, type 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';
@@ -107,20 +109,31 @@ const odkForm = ref<RootNode>();
 const submitPressed = ref(false);
 const initializeFormError = ref<FormInitializationError | null>();
 
-initializeForm(props.formXml, {
-	config: {
-		fetchFormAttachment: props.fetchFormAttachment,
-		missingResourceBehavior: props.missingResourceBehavior,
-		stateFactory: reactive,
-	},
-})
-	.then((f) => {
-		odkForm.value = f;
-	})
-	.catch((cause) => {
-		initializeFormError.value = new FormInitializationError(cause);
+const init = async () => {
+	const { formXml, fetchFormAttachment, missingResourceBehavior } = props;
+
+	const formResult = await loadForm(formXml, {
+		fetchFormAttachment,
+		missingResourceBehavior,
 	});
 
+	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;
 

packages/web-forms/src/lib/error/FormInitializationError.ts

@@ -2,13 +2,15 @@ import {
 	isUnknownObject,
 	type UnknownObject,
 } from '@getodk/common/lib/runtime-types/shared-type-predicates.ts';
-import type { initializeForm } from '@getodk/xforms-engine';
+import type { createInstance } from '@getodk/xforms-engine';
 
-interface ErrorLikeCause extends UnknownObject {
+interface ErrorLike {
 	readonly message: string;
 	readonly stack?: string | null;
 }
 
+interface ErrorLikeCause extends ErrorLike, UnknownObject {}
+
 const isErrorLikeCause = (cause: unknown): cause is ErrorLikeCause => {
 	if (!isUnknownObject(cause)) {
 		return false;
@@ -24,6 +26,13 @@ const isErrorLikeCause = (cause: unknown): cause is ErrorLikeCause => {
  */
 const UNKNOWN_ERROR_MESSAGE = 'Unknown error';
 
+interface FormInitializationErrorOptions {
+	readonly message: string;
+	readonly cause?: unknown;
+	readonly unknownCauseDetail?: string | null;
+	readonly stack?: string | null;
+}
+
 /**
  * Provides a minimal, uniform representation of most general, known form load
  * failure conditions.
@@ -37,7 +46,7 @@ const UNKNOWN_ERROR_MESSAGE = 'Unknown error';
  * coming refinement.
  *
  * We handle these broad cases, each of which may be produced by a rejected
- * {@link Promise}, as returned by {@link initializeForm}:
+ * {@link Promise}, as returned by {@link createInstance}:
  *
  * 1. Promise is rejected with any {@link Error}, or subclass/inheritor thereof,
  *    as thrown by `@getodk/xforms-engine` or `@getodk/xpath`. These are
@@ -63,7 +72,7 @@ const UNKNOWN_ERROR_MESSAGE = 'Unknown error';
  *    system. We will likely make some meaningful effort on this front as well,
  *    but we accept it will never be exhaustive. Most importantly, we cannot
  *    truly know what types may be thrown (and then passed through as a
- *    {@link Promise} rejection by {@link initializeForm}).
+ *    {@link Promise} rejection by {@link createInstance}).
  *
  * As such where the type of {@link cause} is...
  *
@@ -86,42 +95,64 @@ const UNKNOWN_ERROR_MESSAGE = 'Unknown error';
  * to `@getodk/xforms-engine`.
  */
 export class FormInitializationError extends Error {
-	readonly unknownCauseDetail: string | null;
-	readonly stack?: string | undefined;
-
-	constructor(readonly cause: unknown) {
-		let message: string;
-		let unknownCauseDetail: string | null = null;
-		let stack: string | null = null;
+	static fromError(cause: ErrorLike): FormInitializationError {
+		return new this(cause);
+	}
 
-		// If `initializeForm` rejected with an error, we can derive its message and stack
+	static from(cause: unknown): FormInitializationError {
 		if (cause instanceof Error || isErrorLikeCause(cause)) {
-			message = cause.message;
-			stack = cause.stack ?? null;
-		} else if (isUnknownObject(cause) && typeof cause.message === 'string') {
-			message = cause.message;
-		} else if (typeof cause === 'string') {
-			message = cause;
-		} else {
-			message = 'Unknown error';
+			return this.fromError(cause);
+		}
 
-			try {
-				unknownCauseDetail = JSON.stringify(cause, null, 2);
-			} catch {
-				// Ignore JSON serialization error
-			}
+		if (isUnknownObject(cause) && typeof cause.message === 'string') {
+			return new this({
+				message: cause.message,
+				cause,
+			});
 		}
 
+		if (typeof cause === 'string') {
+			return new this({
+				message: cause,
+				cause,
+			});
+		}
+
+		let unknownCauseDetail: string | null = null;
+
+		try {
+			unknownCauseDetail = JSON.stringify(cause, null, 2);
+		} catch {
+			// Ignore JSON serialization error
+		}
+
+		return new this({
+			message: 'Unknown error',
+			cause,
+			unknownCauseDetail,
+		});
+	}
+
+	readonly cause: unknown;
+	readonly unknownCauseDetail: string | null;
+	readonly stack?: string | undefined;
+
+	private constructor(options: FormInitializationErrorOptions) {
+		let message = options.message;
+
 		// TODO: this occurs when Solid's production build detects a "potential
 		// infinite loop" (i.e. either a form cycle, or potentially a serious bug in
 		// the engine!).
 		if (message === '') {
 			message = 'Unknown error';
 		}
 
+		const { cause, unknownCauseDetail, stack } = options;
+
 		super(message, { cause });
 
-		this.unknownCauseDetail = unknownCauseDetail;
+		this.cause = cause;
+		this.unknownCauseDetail = unknownCauseDetail ?? null;
 
 		if (stack != null) {
 			this.stack = stack;

packages/web-forms/tests/helpers.ts

@@ -1,7 +1,7 @@
 import { xformFixturesByIdentifier } from '@getodk/common/fixtures/xforms.ts';
 import type { AnyFunction } from '@getodk/common/types/helpers.d.ts';
 import type { AnyControlNode, RootNode } from '@getodk/xforms-engine';
-import { initializeForm } from '@getodk/xforms-engine';
+import { createInstance } from '@getodk/xforms-engine';
 import type { MountingOptions } from '@vue/test-utils';
 import PrimeVue from 'primevue/config';
 import type { MockInstance } from 'vitest';
@@ -45,12 +45,13 @@ export const getFormXml = (fileName: string): Promise<string> => {
 
 export const getReactiveForm = async (formPath: string): Promise<RootNode> => {
 	const formXml = await getFormXml(formPath);
-
-	return await initializeForm(formXml, {
-		config: {
+	const instance = await createInstance(formXml, {
+		instance: {
 			stateFactory: reactive,
 		},
 	});
+
+	return instance.root;
 };
 
 type GlobalMountOptions = Required<MountingOptions<unknown>>['global'];