@getodk/xforms-engine 0.5.0 → 0.7.0

package/src/instance/hierarchy.ts

@@ -1,26 +1,23 @@
 import type { Group } from './Group.ts';
 import type { AnyInputControl } from './InputControl.ts';
 import type { AnyModelValue } from './ModelValue.ts';
-import type { Note } from './Note.ts';
+import type { AnyNote } from './Note.ts';
 import type { PrimaryInstance } from './PrimaryInstance.ts';
+import type { AnyRangeControl } from './RangeControl.ts';
 import type { RepeatInstance } from './repeat/RepeatInstance.ts';
 import type { RepeatRangeControlled } from './repeat/RepeatRangeControlled.ts';
 import type { RepeatRangeUncontrolled } from './repeat/RepeatRangeUncontrolled.ts';
 import type { Root } from './Root.ts';
-import type { SelectField } from './SelectField.ts';
+import type { SelectControl } from './SelectControl.ts';
 import type { Subtree } from './Subtree.ts';
 import type { TriggerControl } from './TriggerControl.ts';
-import type { RangeControl } from './unsupported/RangeControl.ts';
-import type { RankControl } from './unsupported/RankControl.ts';
+import type { RankControl } from './RankControl.ts';
 import type { UploadControl } from './unsupported/UploadControl.ts';
 
 export type RepeatRange = RepeatRangeControlled | RepeatRangeUncontrolled;
 
 // prettier-ignore
-export type AnyUnsupportedControl =
-	| RangeControl
-	| RankControl
-	| UploadControl;
+export type AnyUnsupportedControl = UploadControl;
 
 // prettier-ignore
 export type AnyNode =
@@ -31,10 +28,12 @@ export type AnyNode =
 	| Subtree
 	| RepeatRange
 	| RepeatInstance
-	| Note
+	| AnyNote
 	| AnyModelValue
 	| AnyInputControl
-	| SelectField
+	| AnyRangeControl
+	| RankControl
+	| SelectControl
 	| TriggerControl
 	| AnyUnsupportedControl;
 
@@ -65,9 +64,11 @@ export type AnyChildNode =
 	| RepeatRange
 	| RepeatInstance
 	| AnyModelValue
-	| Note
+	| AnyNote
 	| AnyInputControl
-	| SelectField
+	| AnyRangeControl
+	| RankControl
+	| SelectControl
 	| TriggerControl
 	| AnyUnsupportedControl;
 
@@ -78,9 +79,11 @@ export type GeneralChildNode =
 	| Subtree
 	| RepeatRange
 	| AnyModelValue
-	| Note
+	| AnyNote
 	| AnyInputControl
-	| SelectField
+	| AnyRangeControl
+	| RankControl
+	| SelectControl
 	| TriggerControl
 	| AnyUnsupportedControl;
 
@@ -88,8 +91,10 @@ export type GeneralChildNode =
 export type AnyValueNode =
 	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
 	| AnyModelValue
-	| Note
+	| AnyNote
 	| AnyInputControl
-	| SelectField
+	| AnyRangeControl
+	| RankControl
+	| SelectControl
 	| TriggerControl
 	| AnyUnsupportedControl;

package/src/instance/input/InitialInstanceState.ts

@@ -0,0 +1,108 @@
+import { getBlobText } from '@getodk/common/lib/web-compat/blob.ts';
+import { INSTANCE_FILE_NAME } from '../../client/constants.ts';
+import type {
+	EditFormInstanceInput,
+	ResolvableFormInstanceInput,
+} from '../../client/form/EditFormInstance.ts';
+import type { InstanceData } from '../../client/serialization/InstanceData.ts';
+import { ErrorProductionDesignPendingError } from '../../error/ErrorProductionDesignPendingError.ts';
+import type { StaticDocument } from '../../integration/xpath/static-dom/StaticDocument.ts';
+import type { ModelDefinition } from '../../parse/model/ModelDefinition.ts';
+import { parseInstanceXML } from '../../parse/shared/parseInstanceXML.ts';
+import type { XFormDOM } from '../../parse/XFormDOM.ts';
+import { InstanceAttachmentMap } from './InstanceAttachmentMap.ts';
+
+export type InitialInstanceStateSources = readonly [InstanceData, ...InstanceData[]];
+
+interface InitialInstanceStateOptions {
+	readonly instanceXML: string;
+	readonly attachments: InstanceAttachmentMap;
+}
+
+const resolveInstanceXML = async (input: ResolvableFormInstanceInput): Promise<string> => {
+	const instanceResult = await input.resolveInstance();
+
+	if (typeof instanceResult === 'string') {
+		return instanceResult;
+	}
+
+	if (instanceResult instanceof Blob) {
+		return getBlobText(instanceResult);
+	}
+
+	return instanceResult.text();
+};
+
+const parseInstanceDocument = (model: ModelDefinition, instanceXML: string): StaticDocument => {
+	const doc = parseInstanceXML(model, instanceXML);
+
+	/**
+	 * Note: this is presently inferred as nullable. Its presence is _currently_
+	 * enforced by {@link XFormDOM}, though that's definitely not ideal!
+	 *
+	 * @todo we would probably benefit from a single parse function responsible
+	 * for both instance documents (form and input), with all `id` enforcement
+	 * handled in one place (presence in both cases, matching in case of form +
+	 * input). We could then also express this at the type level without weird DOM
+	 * shenanigans in {@link XFormDOM} (which aren't likely to stick around in
+	 * their current state forever!).
+	 */
+	const expectedId = model.instance.root.getAttributeValue('id');
+	const actualId = doc.root.getAttributeValue('id');
+
+	if (expectedId !== actualId) {
+		throw new ErrorProductionDesignPendingError(
+			`Invalid instance input. Expected instance id to be "${expectedId}", got: "${actualId}"`
+		);
+	}
+
+	return doc;
+};
+
+export class InitialInstanceState {
+	static async from(
+		model: ModelDefinition,
+		data: InitialInstanceStateSources
+	): Promise<InitialInstanceState> {
+		return this.resolve(model, {
+			inputType: 'FORM_INSTANCE_INPUT_RESOLVED',
+			data,
+		});
+	}
+
+	static async resolve(
+		model: ModelDefinition,
+		input: EditFormInstanceInput
+	): Promise<InitialInstanceState> {
+		if (input.inputType === 'FORM_INSTANCE_INPUT_RESOLVED') {
+			const { data } = input;
+			const [instanceData] = data;
+			const instanceFile = instanceData.get(INSTANCE_FILE_NAME);
+			const instanceXML = await getBlobText(instanceFile);
+			const attachments = InstanceAttachmentMap.from(data);
+
+			return new this(model, {
+				instanceXML,
+				attachments,
+			});
+		}
+
+		const [instanceXML, attachments] = await Promise.all([
+			resolveInstanceXML(input),
+			InstanceAttachmentMap.resolve(input.attachments),
+		]);
+
+		return new this(model, {
+			instanceXML,
+			attachments,
+		});
+	}
+
+	readonly document: StaticDocument;
+	readonly attachments: InstanceAttachmentMap;
+
+	private constructor(model: ModelDefinition, options: InitialInstanceStateOptions) {
+		this.document = parseInstanceDocument(model, options.instanceXML);
+		this.attachments = options.attachments;
+	}
+}

package/src/instance/input/InstanceAttachmentMap.ts

@@ -0,0 +1,142 @@
+import { INSTANCE_FILE_NAME } from '../../client/constants.ts';
+import type { ResolvableInstanceAttachmentsMap } from '../../client/form/EditFormInstance.ts';
+import { MalformedInstanceDataError } from '../../error/MalformedInstanceDataError.ts';
+
+type InstanceAttachmentMapSourceEntry = readonly [key: string, value: FormDataEntryValue];
+
+interface InstanceAttachmentMapSource {
+	entries(): Iterable<InstanceAttachmentMapSourceEntry>;
+}
+
+type InstanceAttachmentMapSources = readonly [
+	InstanceAttachmentMapSource,
+	...InstanceAttachmentMapSource[],
+];
+
+/**
+ * @todo This currently short-circuits if there are actually any instance
+ * attachments to resolve. As described below, much of the approach is pretty
+ * naive now anyway, and none of it is really "ready" until we have something to
+ * actually _use the instance attachments_ once they're resolved! When we are
+ * ready, the functionality can be unblocked as in
+ * {@link https://github.com/getodk/web-forms/commit/88ee1b91c1f68d53ce9ba551bab334852e1e60cd | this commit}.
+ *
+ * @todo Everything about this is incredibly naive! We should almost certainly
+ * do _at least_ the following:
+ *
+ * - Limit how many attachments we attempt to resolve concurrently
+ * - Lazy resolution of large attachments (i.e. probably streaming, maybe range
+ *   requests, ?)
+ *
+ * @todo Once lazy resolution is a thing, we will **also** need a clear path
+ * from there to eager resolution (i.e. for offline caching: it doesn't make
+ * sense to cache a stream in progress, as it won't load the resource once the
+ * user actually is offline/lacks network access). This may be something we can
+ * evolve gradually!
+ */
+const resolveInstanceAttachmentMapSource = async (
+	input: ResolvableInstanceAttachmentsMap
+): Promise<InstanceAttachmentMapSource> => {
+	const inputEntries = Array.from(input.entries());
+
+	if (inputEntries.length > 0) {
+		const fileNames = Array.from(input.keys());
+		const errors = fileNames.map((fileName) => {
+			return new Error(`Failed to resolve instance attachment with file name "${fileName}"`);
+		});
+
+		throw new AggregateError(errors, 'Not implemented: instance attachment resource resolution');
+	}
+
+	const entries = await Promise.all<InstanceAttachmentMapSourceEntry>(
+		inputEntries.map(async ([fileName, resolveAttachment]) => {
+			const response = await resolveAttachment();
+			const blob = await response.blob();
+			const value = new File([blob], fileName);
+
+			return [fileName, value] as const;
+		})
+	);
+
+	return { entries: () => entries };
+};
+
+interface KeyedInstanceDataFile<Key extends string> extends File {
+	readonly name: Key;
+}
+
+type AssertKeyedInstanceDataFile = <Key extends string>(
+	key: Key,
+	file: File
+) => asserts file is KeyedInstanceDataFile<Key>;
+
+const assertKeyedInstanceDataFile: AssertKeyedInstanceDataFile = (key, file) => {
+	if (file.name !== key) {
+		throw new MalformedInstanceDataError(
+			`Unexpected InstanceData file. Expected file name to match key, got key: ${JSON.stringify(key)} and file name: ${JSON.stringify(file.name)}`
+		);
+	}
+};
+
+type UnknownInstanceDataEntry = readonly [key: string, value: FormDataEntryValue];
+
+type KeyedInstanceDataEntry<Key extends string> = readonly [key: Key, KeyedInstanceDataFile<Key>];
+
+type AssertInstanceDataEntry = <Key extends string>(
+	entry: UnknownInstanceDataEntry
+) => asserts entry is KeyedInstanceDataEntry<Key>;
+
+const assertInstanceDataEntry: AssertInstanceDataEntry = (entry) => {
+	const [key, value] = entry;
+
+	if (!(value instanceof File)) {
+		throw new MalformedInstanceDataError(
+			`Unexpected non-file attachment in InstanceData for key: ${key}`
+		);
+	}
+
+	assertKeyedInstanceDataFile(key, value);
+};
+
+export class InstanceAttachmentMap extends Map<string, File> {
+	static from(sources: InstanceAttachmentMapSources): InstanceAttachmentMap {
+		return new this(sources);
+	}
+
+	/**
+	 * @todo
+	 * @see {@link resolveInstanceAttachmentMapSource}
+	 */
+	static async resolve(input: ResolvableInstanceAttachmentsMap): Promise<InstanceAttachmentMap> {
+		const source = await resolveInstanceAttachmentMapSource(input);
+
+		return new this([source]);
+	}
+
+	private constructor(sources: InstanceAttachmentMapSources) {
+		super();
+
+		for (const source of sources) {
+			for (const entry of source.entries()) {
+				const [key] = entry;
+
+				// Skip the instance XML file: it's not an attachment!
+				if (key === INSTANCE_FILE_NAME) {
+					continue;
+				}
+
+				if (this.has(key)) {
+					throw new MalformedInstanceDataError(
+						`Unexpected InstanceData entry. Duplicate instance attachment for key: ${JSON.stringify(key)}`
+					);
+				}
+
+				assertInstanceDataEntry(entry);
+
+				const [, value] = entry;
+
+				this.set(key, value);
+			}
+		}
+	}
+}

package/src/instance/internal-api/InstanceConfig.ts

@@ -1,16 +1,9 @@
-import type { MissingResourceBehavior } from '../../client/constants.ts';
+import type { FormInstanceConfig } from '../../client/form/FormInstanceConfig.ts';
 import type { OpaqueReactiveObjectFactory } from '../../client/OpaqueReactiveObjectFactory.ts';
-import type { FetchFormAttachment, FetchResource } from '../../client/resources.ts';
-import type { CreateUniqueId } from '../../lib/unique-id.ts';
 
 export interface InstanceConfig {
-	readonly stateFactory: OpaqueReactiveObjectFactory;
-	readonly fetchFormDefinition: FetchResource;
-	readonly fetchFormAttachment: FetchFormAttachment;
-	readonly missingResourceBehavior: MissingResourceBehavior;
-
 	/**
-	 * Uniqueness per form instance session (so e.g. persistence isn't necessary).
+	 * @see {@link FormInstanceConfig.stateFactory}
 	 */
-	readonly createUniqueId: CreateUniqueId;
+	readonly clientStateFactory: OpaqueReactiveObjectFactory;
 }

package/src/instance/internal-api/InstanceValueContext.ts

@@ -1,22 +1,32 @@
+import type { FormInstanceInitializationMode } from '../../client/index.ts';
+import type { StaticLeafElement } from '../../integration/xpath/static-dom/StaticElement.ts';
 import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
 import type { BindComputationExpression } from '../../parse/expression/BindComputationExpression.ts';
+import type { AnyBindPreloadDefinition } from '../../parse/model/BindPreloadDefinition.ts';
 import type { EvaluationContext } from './EvaluationContext.ts';
 
+export interface InstanceValueContextDocument {
+	readonly initializationMode: FormInstanceInitializationMode;
+}
+
 export type DecodeInstanceValue = (value: string) => string;
 
 interface InstanceValueContextDefinitionBind {
+	readonly preload: AnyBindPreloadDefinition | null;
 	readonly calculate: BindComputationExpression<'calculate'> | null;
 	readonly readonly: BindComputationExpression<'readonly'>;
 }
 
 export interface InstanceValueContextDefinition {
 	readonly bind: InstanceValueContextDefinitionBind;
-	readonly defaultValue: string;
+	readonly template: StaticLeafElement;
 }
 
 export interface InstanceValueContext extends EvaluationContext {
 	readonly scope: ReactiveScope;
+	readonly rootDocument: InstanceValueContextDocument;
 	readonly definition: InstanceValueContextDefinition;
+	readonly instanceNode: StaticLeafElement | null;
 	readonly decodeInstanceValue: DecodeInstanceValue;
 
 	isReadonly(): boolean;

package/src/instance/internal-api/serialization/ClientReactiveSerializableInstance.ts

@@ -0,0 +1,20 @@
+import type { SubmissionMeta } from '../../../client/submission/SubmissionMeta.ts';
+import type { AncestorNodeValidationState } from '../../../client/validation.ts';
+import type { Root } from '../../Root.ts';
+import type {
+	ClientReactiveSerializableParentNode,
+	ClientReactiveSerializableParentNodeDefinition,
+} from './ClientReactiveSerializableParentNode.ts';
+
+interface ClientReactiveSerializableInstanceDefinition
+	extends ClientReactiveSerializableParentNodeDefinition {
+	readonly submission: SubmissionMeta;
+}
+
+export interface ClientReactiveSerializableInstance
+	extends ClientReactiveSerializableParentNode<Root> {
+	readonly definition: ClientReactiveSerializableInstanceDefinition;
+	readonly root: Root;
+	readonly parent: null;
+	readonly validationState: AncestorNodeValidationState;
+}

package/src/instance/internal-api/serialization/ClientReactiveSerializableLeafNode.ts

@@ -0,0 +1,43 @@
+import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
+import type { QualifiedName } from '../../../lib/names/QualifiedName.ts';
+import type { EscapedXMLText } from '../../../lib/xml-serialization.ts';
+import type {
+	ClientReactiveSerializableChildNode,
+	ClientReactiveSerializableParentNode,
+} from './ClientReactiveSerializableParentNode.ts';
+
+interface ClientReactiveSerializableLeafNodeCurrentState<RuntimeValue> {
+	get relevant(): boolean;
+	get value(): RuntimeValue;
+}
+
+export type SerializedInstanceValue = string;
+
+interface ClientReactiveSerializableLeafNodeDefinition {
+	readonly qualifiedName: QualifiedName;
+}
+
+export interface ClientReactiveSerializableLeafNode<RuntimeValue> {
+	readonly definition: ClientReactiveSerializableLeafNodeDefinition;
+	readonly parent: ClientReactiveSerializableParentNode<ClientReactiveSerializableChildNode>;
+	readonly currentState: ClientReactiveSerializableLeafNodeCurrentState<RuntimeValue>;
+
+	/**
+	 * A client-reactive serializble leaf node is responsible for producing a
+	 * string representation of its value state, suitable for instance
+	 * serialization. It **MUST NOT** perform any further instance
+	 * serialization-specific serialization duties: in particular, the value
+	 * **MUST NOT** be escaped for XML. This responsibility is delegated up the
+	 * stack, to avoid repeat escaping.
+	 *
+	 * Note: excluding {@link EscapedXMLText} here does not have an effect on the
+	 * type system, it is a documentation-only hint, to help guard against future
+	 * double-escaping mistakes.
+	 */
+	readonly encodeValue: (
+		this: unknown,
+		runtimeValue: RuntimeValue
+	) => Exclude<string, EscapedXMLText>;
+
+	readonly instanceState: InstanceState;
+}

package/src/instance/internal-api/serialization/ClientReactiveSerializableParentNode.ts

@@ -0,0 +1,26 @@
+import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
+import type { QualifiedName } from '../../../lib/names/QualifiedName.ts';
+
+export interface ClientReactiveSerializableChildNode {
+	readonly instanceState: InstanceState;
+}
+
+export interface ClientReactiveSerializableParentNodeCurrentState<
+	Child extends ClientReactiveSerializableChildNode,
+> {
+	get relevant(): boolean;
+	get children(): readonly Child[];
+}
+
+export interface ClientReactiveSerializableParentNodeDefinition {
+	readonly qualifiedName: QualifiedName;
+}
+
+export interface ClientReactiveSerializableParentNode<
+	Child extends ClientReactiveSerializableChildNode,
+> {
+	readonly definition: ClientReactiveSerializableParentNodeDefinition;
+	readonly parent: ClientReactiveSerializableParentNode<ClientReactiveSerializableChildNode> | null;
+	readonly currentState: ClientReactiveSerializableParentNodeCurrentState<Child>;
+	readonly instanceState: InstanceState;
+}

package/src/instance/internal-api/serialization/ClientReactiveSerializableTemplatedNode.ts

@@ -0,0 +1,24 @@
+import type { TemplatedNodeAttributeSerializationError } from '../../../error/TemplatedNodeAttributeSerializationError.ts';
+import type { StaticElement } from '../../../integration/xpath/static-dom/StaticElement.ts';
+import type { GeneralChildNode } from '../../hierarchy.ts';
+import type {
+	ClientReactiveSerializableParentNode,
+	ClientReactiveSerializableParentNodeCurrentState,
+	ClientReactiveSerializableParentNodeDefinition,
+} from './ClientReactiveSerializableParentNode.ts';
+
+export interface ClientReactiveSerializableTemplatedNodeCurrentState
+	extends ClientReactiveSerializableParentNodeCurrentState<GeneralChildNode> {
+	/** @see {@link TemplatedNodeAttributeSerializationError} */
+	get attributes(): unknown;
+}
+
+export interface ClientReactiveSerializableTemplatedNodeDefinition
+	extends ClientReactiveSerializableParentNodeDefinition {
+	readonly template: StaticElement;
+}
+
+export interface ClientReactiveSerializableTemplatedNode
+	extends ClientReactiveSerializableParentNode<GeneralChildNode> {
+	readonly currentState: ClientReactiveSerializableTemplatedNodeCurrentState;
+}

package/src/instance/internal-api/serialization/ClientReactiveSerializableValueNode.ts

@@ -0,0 +1,28 @@
+import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
+import type { QualifiedName } from '../../../lib/names/QualifiedName.ts';
+import type {
+	ClientReactiveSerializableChildNode,
+	ClientReactiveSerializableParentNode,
+} from './ClientReactiveSerializableParentNode.ts';
+
+export type SerializedInstanceValue = string;
+
+interface ClientReactiveSerializableValueNodeCurrentState {
+	get relevant(): boolean;
+
+	/**
+	 * @todo Consider moving into {@link InstanceState}
+	 */
+	get instanceValue(): SerializedInstanceValue;
+}
+
+interface ClientReactiveSerializableValueNodeDefinition {
+	readonly qualifiedName: QualifiedName;
+}
+
+export interface ClientReactiveSerializableValueNode {
+	readonly definition: ClientReactiveSerializableValueNodeDefinition;
+	readonly parent: ClientReactiveSerializableParentNode<ClientReactiveSerializableChildNode>;
+	readonly currentState: ClientReactiveSerializableValueNodeCurrentState;
+	readonly instanceState: InstanceState;
+}