@getodk/xforms-engine 0.7.0 → 0.8.0

package/src/instance/children/buildChildren.ts

@@ -6,7 +6,7 @@ import type { RankDefinition } from '../../client/RankNode.ts';
 import type { SelectDefinition } from '../../client/SelectNode.ts';
 import type { SubtreeDefinition } from '../../client/SubtreeNode.ts';
 import type { TriggerNodeDefinition } from '../../client/TriggerNode.ts';
-import type { UploadNodeDefinition } from '../../client/unsupported/UploadNode.ts';
+import type { UploadDefinition } from '../../client/UploadNode.ts';
 import { ErrorProductionDesignPendingError } from '../../error/ErrorProductionDesignPendingError.ts';
 import type { LeafNodeDefinition } from '../../parse/model/LeafNodeDefinition.ts';
 import { NoteNodeDefinition } from '../../parse/model/NoteNodeDefinition.ts';
@@ -28,7 +28,7 @@ import { RepeatRangeUncontrolled } from '../repeat/RepeatRangeUncontrolled.ts';
 import { SelectControl } from '../SelectControl.ts';
 import { Subtree } from '../Subtree.ts';
 import { TriggerControl } from '../TriggerControl.ts';
-import { UploadControl } from '../unsupported/UploadControl.ts';
+import { UploadControl } from '../UploadControl.ts';
 import { childrenInitOptions } from './childrenInitOptions.ts';
 
 const isSubtreeDefinition = (
@@ -37,9 +37,6 @@ const isSubtreeDefinition = (
 	return definition.bodyElement == null;
 };
 
-// prettier-ignore
-type AnyUnsupportedControlDefinition = UploadNodeDefinition;
-
 // prettier-ignore
 type ControlNodeDefinition =
 	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
@@ -48,7 +45,7 @@ type ControlNodeDefinition =
 	| SelectDefinition
 	| RankDefinition
 	| TriggerNodeDefinition
-	| AnyUnsupportedControlDefinition;
+	| UploadDefinition;
 
 type AnyLeafNodeDefinition = ControlNodeDefinition | ModelValueDefinition;
 
@@ -123,7 +120,7 @@ const isTriggerNodeDefinition = (
 
 const isUploadNodeDefinition = (
 	definition: ControlNodeDefinition
-): definition is UploadNodeDefinition => {
+): definition is UploadDefinition => {
 	return definition.bodyElement.type === 'upload';
 };
 
@@ -192,7 +189,7 @@ export const buildChildren = (parent: GeneralParentNode): GeneralChildNode[] =>
 				}
 
 				if (isUploadNodeDefinition(leafChild)) {
-					return new UploadControl(parent, instanceNode, leafChild);
+					return UploadControl.from(parent, instanceNode, leafChild);
 				}
 
 				throw new UnreachableError(leafChild);

package/src/instance/hierarchy.ts

@@ -4,6 +4,7 @@ import type { AnyModelValue } from './ModelValue.ts';
 import type { AnyNote } from './Note.ts';
 import type { PrimaryInstance } from './PrimaryInstance.ts';
 import type { AnyRangeControl } from './RangeControl.ts';
+import type { RankControl } from './RankControl.ts';
 import type { RepeatInstance } from './repeat/RepeatInstance.ts';
 import type { RepeatRangeControlled } from './repeat/RepeatRangeControlled.ts';
 import type { RepeatRangeUncontrolled } from './repeat/RepeatRangeUncontrolled.ts';
@@ -11,14 +12,10 @@ import type { Root } from './Root.ts';
 import type { SelectControl } from './SelectControl.ts';
 import type { Subtree } from './Subtree.ts';
 import type { TriggerControl } from './TriggerControl.ts';
-import type { RankControl } from './RankControl.ts';
-import type { UploadControl } from './unsupported/UploadControl.ts';
+import type { UploadControl } from './UploadControl.ts';
 
 export type RepeatRange = RepeatRangeControlled | RepeatRangeUncontrolled;
 
-// prettier-ignore
-export type AnyUnsupportedControl = UploadControl;
-
 // prettier-ignore
 export type AnyNode =
 	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
@@ -35,7 +32,7 @@ export type AnyNode =
 	| RankControl
 	| SelectControl
 	| TriggerControl
-	| AnyUnsupportedControl;
+	| UploadControl;
 
 // prettier-ignore
 export type AnyParentNode =
@@ -70,7 +67,7 @@ export type AnyChildNode =
 	| RankControl
 	| SelectControl
 	| TriggerControl
-	| AnyUnsupportedControl;
+	| UploadControl;
 
 // prettier-ignore
 export type GeneralChildNode =
@@ -85,7 +82,7 @@ export type GeneralChildNode =
 	| RankControl
 	| SelectControl
 	| TriggerControl
-	| AnyUnsupportedControl;
+	| UploadControl;
 
 // prettier-ignore
 export type AnyValueNode =
@@ -97,4 +94,4 @@ export type AnyValueNode =
 	| RankControl
 	| SelectControl
 	| TriggerControl
-	| AnyUnsupportedControl;
+	| UploadControl;

package/src/instance/input/InstanceAttachmentMap.ts

@@ -1,6 +1,9 @@
+import { getBlobData } from '@getodk/common/lib/web-compat/blob.ts';
 import { INSTANCE_FILE_NAME } from '../../client/constants.ts';
 import type { ResolvableInstanceAttachmentsMap } from '../../client/form/EditFormInstance.ts';
 import { MalformedInstanceDataError } from '../../error/MalformedInstanceDataError.ts';
+import { getResponseContentType } from '../../lib/resource-helpers.ts';
+import type { FetchResourceResponse } from '../resource.ts';
 
 type InstanceAttachmentMapSourceEntry = readonly [key: string, value: FormDataEntryValue];
 
@@ -13,14 +16,35 @@ type InstanceAttachmentMapSources = readonly [
 	...InstanceAttachmentMapSource[],
 ];
 
+const DEFAULT_ATTACHMENT_TYPE = 'application/octet-stream';
+
+const resolveContentType = (response: FetchResourceResponse, blob: Blob): string => {
+	let result = blob.type;
+
+	if (result === '') {
+		result = getResponseContentType(response) ?? result;
+	}
+
+	if (result === '') {
+		return DEFAULT_ATTACHMENT_TYPE;
+	}
+
+	return result;
+};
+
+const resolveInstanceAttachmentFile = async (
+	response: FetchResourceResponse,
+	fileName: string
+): Promise<File> => {
+	const blob = await response.blob();
+	const blobData = await getBlobData(blob);
+
+	return new File([blobData], fileName, {
+		type: resolveContentType(response, blob),
+	});
+};
+
 /**
- * @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:
  *
@@ -37,22 +61,10 @@ type InstanceAttachmentMapSources = readonly [
 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]) => {
+		Array.from(input.entries()).map(async ([fileName, resolveAttachment]) => {
 			const response = await resolveAttachment();
-			const blob = await response.blob();
-			const value = new File([blob], fileName);
+			const value = await resolveInstanceAttachmentFile(response, fileName);
 
 			return [fileName, value] as const;
 		})

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

@@ -0,0 +1,20 @@
+import type { Accessor } from 'solid-js';
+import type { FormNodeID } from '../../client/identity.ts';
+import type { StaticLeafElement } from '../../integration/xpath/static-dom/StaticElement.ts';
+import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
+import type { InstanceAttachmentsState } from '../attachments/InstanceAttachmentsState.ts';
+import type { InstanceConfig } from './InstanceConfig.ts';
+
+interface InstanceAttachmentRootDocument {
+	readonly attachments: InstanceAttachmentsState;
+}
+
+export interface InstanceAttachmentContext {
+	readonly instanceConfig: InstanceConfig;
+	readonly scope: ReactiveScope;
+	readonly rootDocument: InstanceAttachmentRootDocument;
+	readonly nodeId: FormNodeID;
+	readonly instanceNode: StaticLeafElement | null;
+	readonly isRelevant: Accessor<boolean>;
+	readonly isAttached: Accessor<boolean>;
+}

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

@@ -1,3 +1,4 @@
+import type { InstanceAttachmentFileNameFactory } from '../../client/attachments/InstanceAttachmentsConfig.ts';
 import type { FormInstanceConfig } from '../../client/form/FormInstanceConfig.ts';
 import type { OpaqueReactiveObjectFactory } from '../../client/OpaqueReactiveObjectFactory.ts';
 
@@ -6,4 +7,6 @@ export interface InstanceConfig {
 	 * @see {@link FormInstanceConfig.stateFactory}
 	 */
 	readonly clientStateFactory: OpaqueReactiveObjectFactory;
+
+	readonly computeAttachmentName: InstanceAttachmentFileNameFactory;
 }

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

@@ -1,5 +1,6 @@
 import type { SubmissionMeta } from '../../../client/submission/SubmissionMeta.ts';
 import type { AncestorNodeValidationState } from '../../../client/validation.ts';
+import type { InstanceAttachmentsState } from '../../attachments/InstanceAttachmentsState.ts';
 import type { Root } from '../../Root.ts';
 import type {
 	ClientReactiveSerializableParentNode,
@@ -16,5 +17,6 @@ export interface ClientReactiveSerializableInstance
 	readonly definition: ClientReactiveSerializableInstanceDefinition;
 	readonly root: Root;
 	readonly parent: null;
+	readonly attachments: InstanceAttachmentsState;
 	readonly validationState: AncestorNodeValidationState;
 }

package/src/lib/client-reactivity/instance-state/prepareInstancePayload.ts

@@ -1,4 +1,5 @@
 import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
+import { bestFitDecreasing } from 'bin-packer';
 import { INSTANCE_FILE_NAME, INSTANCE_FILE_TYPE } from '../../../client/constants.ts';
 import type { InstanceData as ClientInstanceData } from '../../../client/serialization/InstanceData.ts';
 import type { InstanceFile as ClientInstanceFile } from '../../../client/serialization/InstanceFile.ts';
@@ -10,8 +11,22 @@ import type {
 import type { InstancePayloadType } from '../../../client/serialization/InstancePayloadOptions.ts';
 import type { SubmissionMeta } from '../../../client/submission/SubmissionMeta.ts';
 import type { DescendantNodeViolationReference } from '../../../client/validation.ts';
+import { ErrorProductionDesignPendingError } from '../../../error/ErrorProductionDesignPendingError.ts';
+import type { InstanceAttachmentsState } from '../../../instance/attachments/InstanceAttachmentsState.ts';
 import type { ClientReactiveSerializableInstance } from '../../../instance/internal-api/serialization/ClientReactiveSerializableInstance.ts';
 
+const collectInstanceAttachmentFiles = (attachments: InstanceAttachmentsState): readonly File[] => {
+	const files = Array.from(attachments.entries()).map(([context, attachment]) => {
+		if (!context.isAttached() || !context.isRelevant()) {
+			return null;
+		}
+
+		return attachment.getValue();
+	});
+
+	return files.filter((file) => file != null);
+};
+
 class InstanceFile extends File implements ClientInstanceFile {
 	override readonly name = INSTANCE_FILE_NAME;
 	override readonly type = INSTANCE_FILE_TYPE;
@@ -25,10 +40,26 @@ class InstanceFile extends File implements ClientInstanceFile {
 	}
 }
 
+type AssertFile = (value: FormDataEntryValue) => asserts value is File;
+
+const assertFile: AssertFile = (value) => {
+	if (!(value instanceof File)) {
+		throw new ErrorProductionDesignPendingError('Expected an instance of File');
+	}
+};
+
 type AssertInstanceData = (data: FormData) => asserts data is ClientInstanceData;
 
 const assertInstanceData: AssertInstanceData = (data) => {
-	const instanceFile = data.get(INSTANCE_FILE_NAME);
+	let instanceFile: File | null = null;
+
+	for (const [key, value] of data.entries()) {
+		assertFile(value);
+
+		if (key === INSTANCE_FILE_NAME) {
+			instanceFile = value;
+		}
+	}
 
 	if (!(instanceFile instanceof InstanceFile)) {
 		throw new Error(`Invalid InstanceData`);
@@ -114,6 +145,43 @@ interface ChunkedInstancePayloadOptions {
 	readonly maxSize: number;
 }
 
+type PartitionedInstanceData = readonly [ClientInstanceData, ...ClientInstanceData[]];
+
+const partitionInstanceData = (
+	instanceFile: InstanceFile,
+	attachments: readonly File[],
+	options: ChunkedInstancePayloadOptions
+): PartitionedInstanceData => {
+	const { maxSize } = options;
+	const maxAttachmentSize = maxSize - instanceFile.size;
+	const { bins, oversized } = bestFitDecreasing(
+		attachments,
+		(attachment) => {
+			return attachment.size;
+		},
+		maxAttachmentSize
+	);
+
+	const errors = oversized.map((attachment) => {
+		return new Error(
+			`Combined size of instance XML (${instanceFile.size}) and attachment (${attachment.size}) exceeds maxSize (${maxSize}).`
+		);
+	});
+
+	if (errors.length > 0) {
+		throw new AggregateError(errors, 'Failed to produce chunked instance payload');
+	}
+
+	const [
+		// Ensure at least one `InstanceData` is produced, in case there are no
+		// attachments present at all
+		head = InstanceData.from(instanceFile, []),
+		...tail
+	] = bins.map((bin) => InstanceData.from(instanceFile, bin));
+
+	return [head, ...tail];
+};
+
 const chunkedInstancePayload = (
 	validation: InstanceStateValidation,
 	submissionMeta: SubmissionMeta,
@@ -121,17 +189,13 @@ const chunkedInstancePayload = (
 	attachments: readonly File[],
 	options: ChunkedInstancePayloadOptions
 ): ChunkedInstancePayload => {
-	if (attachments.length > 0 || options.maxSize !== Infinity) {
-		throw new Error('InstancePayload chunking pending implementation');
-	}
-
-	const data = InstanceData.from(instanceFile, attachments);
+	const data = partitionInstanceData(instanceFile, attachments, options);
 
 	return {
 		payloadType: 'chunked',
 		...validation,
 		submissionMeta,
-		data: [data],
+		data,
 	};
 };
 
@@ -147,7 +211,7 @@ export const prepareInstancePayload = <PayloadType extends InstancePayloadType>(
 	const validation = validateInstance(instanceRoot);
 	const submissionMeta = instanceRoot.definition.submission;
 	const instanceFile = new InstanceFile(instanceRoot);
-	const attachments: readonly File[] = [];
+	const attachments = collectInstanceAttachmentFiles(instanceRoot.attachments);
 
 	switch (options.payloadType) {
 		case 'chunked':

package/src/lib/reactivity/createInstanceAttachment.ts

@@ -0,0 +1,212 @@
+import { createMemo, createSignal } from 'solid-js';
+import type { FormNodeID } from '../../client/identity.ts';
+import { ErrorProductionDesignPendingError } from '../../error/ErrorProductionDesignPendingError.ts';
+import type { InstanceAttachmentFileName } from '../../instance/attachments/InstanceAttachment.ts';
+import { InstanceAttachment } from '../../instance/attachments/InstanceAttachment.ts';
+import type { InstanceAttachmentContext } from '../../instance/internal-api/InstanceAttachmentContext.ts';
+import type { DecodeInstanceValue } from '../../instance/internal-api/InstanceValueContext.ts';
+import type { SimpleAtomicStateSetter } from './types.ts';
+
+type FileNameExtension = `.${string}`;
+
+type AssertFileNameExtension = (value: string) => asserts value is FileNameExtension;
+
+const assertFileNameExtension: AssertFileNameExtension = (value) => {
+	if (!value.startsWith('.')) {
+		throw new ErrorProductionDesignPendingError('Expected file name extension to start with "."');
+	}
+};
+
+interface SplitFileNameResult {
+	readonly basename: string;
+	readonly extension: FileNameExtension | null;
+}
+
+const EXTENSION_PATTERN = /\.[^.]+?$/;
+
+interface SearchPatternResult extends Array<string> {
+	readonly 0?: string;
+	readonly index?: number;
+}
+
+const searchPattern = (pattern: RegExp, string: string): SearchPatternResult => {
+	return pattern.exec(string) ?? [];
+};
+
+const splitFileName = (fileName: string): SplitFileNameResult => {
+	const extensionMatches = searchPattern(EXTENSION_PATTERN, fileName);
+	const [extension = null] = extensionMatches;
+	const basename = fileName.slice(0, extensionMatches.index);
+
+	if (extension == null) {
+		return {
+			basename,
+			extension,
+		};
+	}
+
+	assertFileNameExtension(extension);
+
+	return {
+		basename,
+		extension,
+	};
+};
+
+export type InstanceAttachmentRuntimeValue = File | null;
+
+export type InstanceAttachmentFormDataEntry = readonly [
+	key: InstanceAttachmentFileName,
+	value: NonNullable<InstanceAttachmentRuntimeValue>,
+];
+
+interface InstanceAttachmentValueOptions {
+	readonly nodeId: FormNodeID;
+	readonly writtenAt: Date | null;
+	readonly file: InstanceAttachmentRuntimeValue;
+}
+
+interface BaseInstanceAttachmentState {
+	readonly computedName: string | null;
+	readonly intrinsicName: string | null;
+	readonly file: InstanceAttachmentRuntimeValue;
+}
+
+interface BlankInstanceAttachmentState extends BaseInstanceAttachmentState {
+	readonly computedName: null;
+	readonly intrinsicName: null;
+	readonly file: null;
+}
+
+interface NonBlankInstanceAttachmentState extends BaseInstanceAttachmentState {
+	readonly computedName: string | null;
+	readonly intrinsicName: string;
+	readonly file: NonNullable<InstanceAttachmentRuntimeValue>;
+}
+
+// prettier-ignore
+type InstanceAttachmentState =
+	| BlankInstanceAttachmentState
+	| NonBlankInstanceAttachmentState;
+
+const instanceAttachmentState = (
+	context: InstanceAttachmentContext,
+	options: InstanceAttachmentValueOptions
+): InstanceAttachmentState => {
+	const { nodeId, file, writtenAt } = options;
+
+	// No file -> no intrinsic name, no name to compute
+	if (file == null) {
+		return {
+			computedName: null,
+			intrinsicName: null,
+			file: null,
+		};
+	}
+
+	const intrinsicName = file.name;
+
+	// File exists, not written by client -> preserve instance input name
+	if (writtenAt == null) {
+		return {
+			computedName: null,
+			intrinsicName,
+			file,
+		};
+	}
+
+	// File was written by client, name is computed as configured by client
+	const { basename, extension } = splitFileName(intrinsicName);
+	const computedName = context.instanceConfig.computeAttachmentName({
+		nodeId,
+		writtenAt,
+		basename,
+		extension,
+	});
+
+	return {
+		computedName,
+		intrinsicName,
+		file,
+	};
+};
+
+export const createInstanceAttachment = (
+	context: InstanceAttachmentContext
+): InstanceAttachment => {
+	return context.scope.runTask(() => {
+		const { rootDocument, nodeId } = context;
+		const { attachments } = rootDocument;
+		const file = attachments.getInitialFileValue(context.instanceNode);
+		const initialState = instanceAttachmentState(context, {
+			nodeId,
+			file,
+			writtenAt: null,
+		});
+
+		const [getState, setState] = createSignal<InstanceAttachmentState>(initialState);
+
+		const decodeInstanceValue: DecodeInstanceValue = (value) => {
+			const { computedName, intrinsicName } = getState();
+
+			if (value === '') {
+				if (computedName != null || intrinsicName != null) {
+					throw new ErrorProductionDesignPendingError(
+						`Unexpected file name reference. Expected one of "${computedName}", "${intrinsicName}", got: ""`
+					);
+				}
+			}
+
+			if (value === intrinsicName) {
+				return computedName ?? intrinsicName;
+			}
+
+			if (value === computedName) {
+				return computedName;
+			}
+
+			throw new ErrorProductionDesignPendingError(
+				`Unexpected file name reference. Expected one of "${computedName}", "${intrinsicName}", got: "${value}"`
+			);
+		};
+
+		const getValue = createMemo(() => {
+			const { computedName, file: currentFile } = getState();
+
+			if (computedName == null) {
+				return currentFile;
+			}
+
+			return new File([currentFile], computedName, {
+				type: currentFile.type,
+			});
+		});
+		const setValue: SimpleAtomicStateSetter<InstanceAttachmentRuntimeValue> = (value) => {
+			const updatedState = instanceAttachmentState(context, {
+				nodeId,
+				file: value,
+				writtenAt: new Date(),
+			});
+
+			return setState(updatedState).file;
+		};
+		const valueState = [getValue, setValue] as const;
+
+		const getFileName = createMemo(() => {
+			const { computedName, intrinsicName } = getState();
+
+			return computedName ?? intrinsicName;
+		});
+		const getInstanceValue = createMemo(() => getFileName() ?? '');
+
+		return InstanceAttachment.init(context, {
+			getFileName,
+			getInstanceValue,
+			decodeInstanceValue,
+
+			getValue,
+			setValue,
+			valueState,
+		});
+	});
+};

package/src/lib/resource-helpers.ts

@@ -0,0 +1,33 @@
+import type { FetchResourceResponse } from '../client/resources.ts';
+
+const CONTENT_TYPE_CHARSET_PATTERN = /\s*;\s*charset\s*=.*$/;
+
+const stripContentTypeCharset = (contentType: string): string => {
+	return contentType.replace(CONTENT_TYPE_CHARSET_PATTERN, '');
+};
+
+export const getResponseContentType = (response: FetchResourceResponse): string | null => {
+	const { headers } = response;
+
+	if (headers == null) {
+		return null;
+	}
+
+	const contentType = headers.get('content-type');
+
+	if (contentType != null) {
+		return stripContentTypeCharset(contentType);
+	}
+
+	if (headers instanceof Headers) {
+		return contentType;
+	}
+
+	for (const [header, value] of headers) {
+		if (header.toLowerCase() === 'content-type') {
+			return stripContentTypeCharset(value);
+		}
+	}
+
+	return null;
+};

package/src/parse/XFormDOM.ts

@@ -104,9 +104,7 @@ const normalizeDefaultMetaBindings = (
 	let meta = getMetaElement(primaryInstanceRoot);
 	let instanceID = getMetaChildElement(meta, 'instanceID');
 
-	if (meta == null) {
-		meta = createNamespacedChildElement(primaryInstanceRoot, OPENROSA_XFORMS_NAMESPACE_URI, 'meta');
-	}
+	meta ??= createNamespacedChildElement(primaryInstanceRoot, OPENROSA_XFORMS_NAMESPACE_URI, 'meta');
 
 	if (instanceID == null) {
 		instanceID = createNamespacedChildElement(meta, meta.namespaceURI, 'instanceID');

package/src/parse/body/BodyDefinition.ts

@@ -207,6 +207,10 @@ export class BodyDefinition extends DependencyContext implements BodyElementPare
 		return this.elementsByReference.get(reference) ?? null;
 	}
 
+	getBodyElementType(reference: BodyElementReference): AnyBodyElementType | null {
+		return this.elementsByReference.getBodyElementType(reference);
+	}
+
 	getChildElementDefinitions(
 		form: XFormDefinition,
 		parent: BodyElementParentContext,