@getodk/xforms-engine 0.16.1 → 0.17.0

package/src/parse/XFormDOM.ts

@@ -10,8 +10,13 @@ import type {
 } from '@getodk/common/types/dom.ts';
 import { DefaultEvaluator } from '@getodk/xpath';
 
+export const SET_VALUE_LOCAL_NAME = 'setvalue';
+export const SET_GEOPOINT_LOCAL_NAME = 'odk:setgeopoint';
+
 interface DOMBindElement extends KnownAttributeLocalNamedElement<'bind', 'nodeset'> {}
-interface DOMSetValueElement extends KnownAttributeLocalNamedElement<'setvalue', 'event'> {}
+export interface DOMSetValueElement extends KnownAttributeLocalNamedElement<'setvalue', 'event'> {}
+export interface DOMSetGeopointElement
+	extends KnownAttributeLocalNamedElement<'odk:setgeopoint', 'event'> {}
 
 const getMetaElement = (primaryInstanceRoot: Element): Element | null => {
 	for (const child of primaryInstanceRoot.children) {
@@ -325,6 +330,15 @@ export class XFormDOM {
 		return new this(sourceXML, { isNormalized: false });
 	}
 
+	isInstanceID = (nodeset: string) => {
+		const meta = getMetaElement(this.primaryInstanceRoot);
+		const instanceId = meta && getMetaChildElement(meta, 'instanceID');
+		return (
+			instanceId &&
+			nodeset === `/${this.primaryInstanceRoot.nodeName}/${meta.nodeName}/${instanceId.nodeName}`
+		);
+	};
+
 	protected readonly normalizedXML: string;
 
 	// Commonly accessed landmark nodes
@@ -338,6 +352,7 @@ export class XFormDOM {
 	readonly model: Element;
 	readonly binds: readonly DOMBindElement[];
 	readonly setValues: readonly DOMSetValueElement[];
+	readonly setGeopoints: readonly DOMSetGeopointElement[];
 	readonly primaryInstance: Element;
 	readonly primaryInstanceRoot: Element;
 
@@ -371,11 +386,15 @@ export class XFormDOM {
 			}
 		);
 		const setValues: readonly DOMSetValueElement[] = evaluator.evaluateNodes<DOMSetValueElement>(
-			'./xf:setvalue[@event]',
+			`./xf:${SET_VALUE_LOCAL_NAME}[@event]`,
 			{
 				contextNode: model,
 			}
 		);
+		const setGeopoints: readonly DOMSetGeopointElement[] =
+			evaluator.evaluateNodes<DOMSetGeopointElement>(`./${SET_GEOPOINT_LOCAL_NAME}[@event]`, {
+				contextNode: model,
+			});
 
 		const instances = evaluator.evaluateNodes<DOMInstanceElement>('./xf:instance', {
 			contextNode: model,
@@ -426,6 +445,7 @@ export class XFormDOM {
 		this.model = model;
 		this.binds = binds;
 		this.setValues = setValues;
+		this.setGeopoints = setGeopoints;
 		this.primaryInstance = primaryInstance;
 		this.primaryInstanceRoot = primaryInstanceRoot;
 		this.itextTranslationElements = itextTranslationElements;

package/src/parse/model/ActionDefinition.ts

@@ -4,12 +4,12 @@ import { type XFormEvent, XFORM_EVENT } from './Event.ts';
 import type { ModelDefinition } from './ModelDefinition.ts';
 
 export class ActionDefinition {
-	static getRef(model: ModelDefinition, setValueElement: Element): string | null {
-		if (setValueElement.hasAttribute('ref')) {
-			return setValueElement.getAttribute('ref') ?? null;
+	static getRef(model: ModelDefinition, element: Element): string | null {
+		if (element.hasAttribute('ref')) {
+			return element.getAttribute('ref') ?? null;
 		}
-		if (setValueElement.hasAttribute('bind')) {
-			const bindId = setValueElement.getAttribute('bind');
+		if (element.hasAttribute('bind')) {
+			const bindId = element.getAttribute('bind');
 			const bindDefinition = Array.from(model.binds.values()).find((definition) => {
 				return definition.bindElement.getAttribute('id') === bindId;
 			});
@@ -58,7 +58,7 @@ export class ActionDefinition {
 		const ref = ActionDefinition.getRef(model, element);
 		if (!ref) {
 			throw new Error(
-				'Invalid setvalue element - you must define either "ref" or "bind" attribute'
+				`Invalid ${element.localName} element - you must define either "ref" or "bind" attribute`
 			);
 		}
 		this.ref = ref;

package/src/parse/model/BindDefinition.ts

@@ -82,7 +82,7 @@ export class BindDefinition<T extends BindType = BindType> extends DependencyCon
 		const parentNodeset = nodeset.replace(/\/[^/]+$/, '');
 
 		this.parentNodeset = parentNodeset.length > 1 ? parentNodeset : null;
-		this.preload = BindPreloadDefinition.from(bindElement);
+		this.preload = BindPreloadDefinition.from(this, bindElement);
 		this.calculate = BindComputationExpression.forComputation(this, 'calculate');
 		this.readonly = BindComputationExpression.forComputation(this, 'readonly');
 		this.relevant = BindComputationExpression.forComputation(this, 'relevant');

package/src/parse/model/BindPreloadDefinition.ts

@@ -2,6 +2,7 @@ import { JAVAROSA_NAMESPACE_URI } from '@getodk/common/constants/xmlns.ts';
 import type { PartiallyKnownString } from '@getodk/common/types/string/PartiallyKnownString.ts';
 import type { AttributeContext } from '../../instance/internal-api/AttributeContext.ts';
 import type { InstanceValueContext } from '../../instance/internal-api/InstanceValueContext.ts';
+import type { BindDefinition } from './BindDefinition.ts';
 import type { BindElement } from './BindElement.ts';
 import { XFORM_EVENT, type XFormEvent } from './Event.ts';
 
@@ -71,20 +72,29 @@ const getPreloadInput = (bindElement: BindElement): AnyPreloadInput | null => {
  * - {@link parameter}, an associated `jr:preloadParams` value
  */
 export class BindPreloadDefinition<Type extends PreloadType> implements PreloadInput<Type> {
-	static from(bindElement: BindElement): AnyBindPreloadDefinition | null {
+	static from(
+		definition: BindDefinition,
+		bindElement: BindElement
+	): AnyBindPreloadDefinition | null {
 		const input = getPreloadInput(bindElement);
 
 		if (input == null) {
 			return null;
 		}
 
-		return new this(input);
+		const type = input.type;
+		const parameter = input.parameter;
+		let event;
+		if (definition.form.xformDOM.isInstanceID(bindElement.getAttribute('nodeset'))) {
+			event = XFORM_EVENT.odkInstanceLoad;
+		} else if (type === 'timestamp' && parameter === 'end') {
+			event = XFORM_EVENT.xformsRevalidate;
+		} else {
+			event = XFORM_EVENT.odkInstanceFirstLoad;
+		}
+		return new this(type, parameter, event);
 	}
 
-	readonly type: Type;
-	readonly parameter: PreloadParameter<Type>;
-	readonly event: XFormEvent;
-
 	getValue(context: AttributeContext | InstanceValueContext): string | undefined {
 		if (this.type === 'uid') {
 			return context.evaluator.evaluateString(PRELOAD_UID_EXPRESSION);
@@ -113,14 +123,11 @@ export class BindPreloadDefinition<Type extends PreloadType> implements PreloadI
 		return;
 	}
 
-	private constructor(input: PreloadInput<Type>) {
-		this.type = input.type;
-		this.parameter = input.parameter;
-		this.event =
-			this.type === 'timestamp' && this.parameter === 'end'
-				? XFORM_EVENT.xformsRevalidate
-				: XFORM_EVENT.odkInstanceFirstLoad;
-	}
+	private constructor(
+		readonly type: Type,
+		readonly parameter: PreloadParameter<Type>,
+		readonly event: XFormEvent
+	) {}
 }
 
 // prettier-ignore

package/src/parse/model/ModelActionMap.ts

@@ -1,10 +1,16 @@
+import {
+	type DOMSetGeopointElement,
+	type DOMSetValueElement,
+	SET_GEOPOINT_LOCAL_NAME,
+	SET_VALUE_LOCAL_NAME,
+} from '../XFormDOM.ts';
 import { ActionDefinition } from './ActionDefinition.ts';
 import { XFORM_EVENT } from './Event.ts';
 import type { ModelDefinition } from './ModelDefinition.ts';
 
 const REPEAT_REGEX = /(\[[^\]]*\])/gm;
 
-export class ModelActionMap extends Map<string, ActionDefinition> {
+export class ModelActionMap extends Map<string, ActionDefinition[]> {
 	static fromModel(model: ModelDefinition): ModelActionMap {
 		return new this(model);
 	}
@@ -14,24 +20,35 @@ export class ModelActionMap extends Map<string, ActionDefinition> {
 	}
 
 	protected constructor(model: ModelDefinition) {
-		super(
-			model.form.xformDOM.setValues.map((setValueElement) => {
-				const action = new ActionDefinition(model, setValueElement);
-				if (action.events.includes(XFORM_EVENT.odkNewRepeat)) {
-					throw new Error('Model contains "setvalue" element with "odk-new-repeat" event');
-				}
-				const key = ModelActionMap.getKey(action.ref);
-				return [key, action];
-			})
-		);
+		super();
+		this.addAll(model, model.form.xformDOM.setValues, SET_VALUE_LOCAL_NAME);
+		this.addAll(model, model.form.xformDOM.setGeopoints, SET_GEOPOINT_LOCAL_NAME);
 	}
 
-	override get(ref: string): ActionDefinition | undefined {
+	override get(ref: string): ActionDefinition[] | undefined {
 		return super.get(ModelActionMap.getKey(ref));
 	}
 
+	private addAll(
+		model: ModelDefinition,
+		elements: readonly DOMSetGeopointElement[] | readonly DOMSetValueElement[],
+		type: string
+	) {
+		for (const element of elements) {
+			const action = new ActionDefinition(model, element);
+			if (action.events.includes(XFORM_EVENT.odkNewRepeat)) {
+				throw new Error(`Model contains "${type}" element with "odk-new-repeat" event`);
+			}
+			this.add(action);
+		}
+	}
+
 	add(action: ActionDefinition) {
 		const key = ModelActionMap.getKey(action.ref);
-		this.set(key, action);
+		if (this.has(key)) {
+			this.get(key)!.push(action);
+		} else {
+			this.set(key, [action]);
+		}
 	}
 }

package/src/parse/model/ModelDefinition.ts

@@ -1,10 +1,8 @@
 import type { ActiveLanguage } from '../../client/FormLanguage.ts';
 import { ErrorProductionDesignPendingError } from '../../error/ErrorProductionDesignPendingError.ts';
 import type { StaticDocument } from '../../integration/xpath/static-dom/StaticDocument.ts';
-import { TextChunkExpression } from '../expression/TextChunkExpression.ts';
 import { parseStaticDocumentFromDOMSubtree } from '../shared/parseStaticDocumentFromDOMSubtree.ts';
 import type { XFormDefinition } from '../XFormDefinition.ts';
-import { generateItextChunks, type ChunkExpressionsByItextId } from './generateItextChunks.ts';
 import { ItextTranslationsDefinition } from './ItextTranslationsDefinition.ts';
 import { ModelActionMap } from './ModelActionMap.ts';
 import { ModelBindMap } from './ModelBindMap.ts';
@@ -13,6 +11,7 @@ import type { NodeDefinitionMap } from './nodeDefinitionMap.ts';
 import { nodeDefinitionMap } from './nodeDefinitionMap.ts';
 import { RootDefinition } from './RootDefinition.ts';
 import { SubmissionDefinition } from './SubmissionDefinition.ts';
+import { TranslationDefinitionMap } from './TranslationDefinitionMap.ts';
 
 type XformsRevalidateListener = () => void;
 
@@ -23,7 +22,7 @@ export class ModelDefinition {
 	readonly nodes: NodeDefinitionMap;
 	readonly instance: StaticDocument;
 	readonly itextTranslations: ItextTranslationsDefinition;
-	readonly itextChunks: Map<string, ChunkExpressionsByItextId>;
+	readonly itextElements: Map<string, Map<string, Element>>;
 	readonly xformsRevalidateListeners: Map<string, XformsRevalidateListener>;
 
 	constructor(readonly form: XFormDefinition) {
@@ -37,7 +36,7 @@ export class ModelDefinition {
 		this.root = new RootDefinition(form, this, submission, form.body.classes);
 		this.nodes = nodeDefinitionMap(this.root);
 		this.itextTranslations = ItextTranslationsDefinition.from(form.xformDOM);
-		this.itextChunks = generateItextChunks(form.xformDOM.itextTranslationElements);
+		this.itextElements = new TranslationDefinitionMap(form.xformDOM.itextTranslationElements);
 		this.xformsRevalidateListeners = new Map();
 	}
 
@@ -69,12 +68,8 @@ export class ModelDefinition {
 		this.xformsRevalidateListeners.forEach((listener: XformsRevalidateListener) => listener());
 	}
 
-	getTranslationChunks(
-		itextId: string,
-		activeLanguage: ActiveLanguage
-	): ReadonlyArray<TextChunkExpression<'string'>> {
-		const languageMap = this.itextChunks.get(activeLanguage.language);
-		return languageMap?.get(itextId) ?? [];
+	getItextElement(activeLanguage: ActiveLanguage, itextId: string): Element | undefined {
+		return this.itextElements.get(activeLanguage.language)?.get(itextId);
 	}
 
 	toJSON() {

package/src/parse/model/RootDefinition.ts

@@ -3,6 +3,7 @@ import { NamespaceDeclarationMap } from '../../lib/names/NamespaceDeclarationMap
 import { QualifiedName } from '../../lib/names/QualifiedName.ts';
 import type { AnyBodyElementDefinition, BodyClassList } from '../body/BodyDefinition.ts';
 import type { XFormDefinition } from '../XFormDefinition.ts';
+import { SET_GEOPOINT_LOCAL_NAME, SET_VALUE_LOCAL_NAME } from '../XFormDOM.ts';
 import { ActionDefinition } from './ActionDefinition.ts';
 import { AttributeDefinitionMap } from './AttributeDefinitionMap.ts';
 import { GroupDefinition } from './GroupDefinition.ts';
@@ -63,7 +64,7 @@ export class RootDefinition extends NodeDefinition<'root'> {
 			return;
 		}
 		for (const child of bodyElement.element.children) {
-			if (child.nodeName === 'setvalue') {
+			if (child.nodeName === SET_VALUE_LOCAL_NAME || child.nodeName === SET_GEOPOINT_LOCAL_NAME) {
 				const action = new ActionDefinition(this.model, child, source);
 				this.model.actions.add(action);
 			}

package/src/parse/model/SecondaryInstance/sources/CSVExternalSecondaryInstance.ts

@@ -1,83 +1,9 @@
-import type { JRResourceURL } from '@getodk/common/jr-resources/JRResourceURL.ts';
-import * as papa from 'papaparse';
-import { ErrorProductionDesignPendingError } from '../../../../error/ErrorProductionDesignPendingError.ts';
 import type { StaticElementOptions } from '../../../../integration/xpath/static-dom/StaticElement.ts';
 import { defineSecondaryInstance } from '../defineSecondaryInstance.ts';
 import type { SecondaryInstanceDefinition } from '../SecondaryInstancesDefinition.ts';
+import { parseItems } from './external-instance-csv-parser.ts';
 import { ExternalSecondaryInstanceSource } from './ExternalSecondaryInstanceSource.ts';
 
-type CSVColumn = string;
-type CSVRow = readonly CSVColumn[];
-
-type AssertCSVRow = (columns: unknown) => asserts columns is CSVRow;
-
-/**
- * Based on {@link https://github.com/getodk/central-frontend/commit/29cebcc870c9be70ab0d222e3349e34639045d19}
- *
- * Central performs this check for header and rows. A comment is included there for the header check, but the logic is the same in both cases.
- */
-const rejectNullCharacters = (cell: string) => {
-	if (cell.includes('\0')) {
-		throw new ErrorProductionDesignPendingError(`Failed to parse CSV: null character`);
-	}
-};
-
-const assertCSVRow: AssertCSVRow = (columns) => {
-	if (!Array.isArray(columns)) {
-		throw new ErrorProductionDesignPendingError('Failed to parse CSV columns');
-	}
-
-	for (const [index, column] of columns.entries()) {
-		if (typeof column !== 'string') {
-			throw new ErrorProductionDesignPendingError(`Failed to parse CSV column at index ${index}`);
-		}
-
-		rejectNullCharacters(column);
-	}
-};
-
-type AssertPapaparseSuccess = (
-	resourceURL: JRResourceURL,
-	errors: readonly papa.ParseError[]
-) => asserts errors is readonly [];
-
-const assertPapaparseSuccess: AssertPapaparseSuccess = (resourceURL, errors) => {
-	if (errors.length > 0) {
-		const cause = new AggregateError(errors);
-		throw new ErrorProductionDesignPendingError(
-			`Failed to parse CSV external secondary instance ${resourceURL.href}`,
-			{ cause }
-		);
-	}
-};
-
-interface ParsedCSVHeader {
-	readonly columns: CSVRow;
-	readonly errors: readonly [];
-	readonly meta: papa.ParseMeta;
-}
-
-interface ParseCSVOptions {
-	readonly columns: readonly string[];
-	readonly delimiter: string;
-}
-
-const stripTrailingEmptyCells = (columns: CSVRow, row: CSVRow): CSVRow => {
-	const result = row.slice();
-
-	while (result.length > columns.length && result.at(-1) === '') {
-		result.pop();
-	}
-
-	return result;
-};
-
-interface ParsedCSVRows {
-	readonly rows: readonly CSVRow[];
-	readonly errors: readonly [];
-	readonly meta: papa.ParseMeta;
-}
-
 interface CSVExternalSecondaryInstanceItemColumn {
 	readonly columnName: string;
 	readonly cellValue: string;
@@ -120,116 +46,8 @@ const csvExternalSecondaryInstanceDefinition = (
 };
 
 export class CSVExternalSecondaryInstanceSource extends ExternalSecondaryInstanceSource<'csv'> {
-	/**
-	 * Based on
-	 * {@link https://github.com/getodk/central-frontend/blob/42c9277709e593480d1462e28b4be5f1364532b7/src/util/csv.js#L79} (and {@link https://github.com/getodk/central-frontend/blob/42c9277709e593480d1462e28b4be5f1364532b7/src/util/csv.js#L13}).
-	 *
-	 * The most significant deviations at time of writing:
-	 *
-	 * - we have already retrieved the CSV resource, so we are parsing the raw CSV data directly.
-	 * - we have no need for asynchronous/streaming parsing at this point in the
-	 *   form initialization process, so we can dispense with those details of the
-	 *   {@link papa | papaparse} API/config.
-	 */
-	private parseCSVHeader(csvData: string): ParsedCSVHeader {
-		const { data, errors, meta } = papa.parse(csvData, {
-			delimitersToGuess: [',', ';', '\t', '|'],
-			download: false,
-			preview: 1,
-		});
-		const [columns = []] = data;
-
-		assertCSVRow(columns);
-		assertPapaparseSuccess(this.resourceURL, errors);
-
-		return {
-			errors,
-			meta,
-			columns,
-		};
-	}
-
-	/**
-	 * Largely based on {@link https://github.com/getodk/central-frontend/blob/42c9277709e593480d1462e28b4be5f1364532b7/src/util/csv.js#L170}
-	 */
-	private parseCSVRows(csvData: string, options: ParseCSVOptions): ParsedCSVRows {
-		const { columns, delimiter } = options;
-		const { data, errors, meta } = papa.parse(csvData, {
-			delimiter,
-			download: false,
-		});
-
-		assertPapaparseSuccess(this.resourceURL, errors);
-
-		const rowData = data.slice(1);
-		const lastRowIndex = rowData.length - 1;
-
-		let stripLastRow = false;
-
-		const rows = rowData.map((values, index) => {
-			assertCSVRow(values);
-
-			const rowIndex = index + 1;
-
-			// Central: Remove trailing empty cells.
-			const row = stripTrailingEmptyCells(columns, values);
-
-			// Central: Skip trailing empty rows and do not check them for warnings.
-			// Throw for an empty row that is not trailing.
-			if (row.every((cell) => cell === '')) {
-				if (index === lastRowIndex) {
-					stripLastRow = true;
-				} else {
-					throw new ErrorProductionDesignPendingError(
-						`Failed to parse CSV row ${rowIndex}: unexpected empty row`
-					);
-				}
-			}
-
-			// Central: Throw if there are too many cells.
-			if (row.length > columns.length) {
-				throw new ErrorProductionDesignPendingError(
-					`Failed to parse CSV row ${rowIndex}: expected ${columns.length} columns, got ${row.length}`
-				);
-			}
-
-			return row;
-		});
-
-		if (stripLastRow) {
-			rows.pop();
-		}
-
-		return {
-			errors,
-			meta,
-			rows,
-		};
-	}
-
-	private toItems(
-		columns: CSVRow,
-		rows: readonly CSVRow[]
-	): readonly CSVExternalSecondaryInstanceItem[] {
-		return rows.map((row) => {
-			return columns.map((columnName, index) => {
-				return {
-					columnName,
-					cellValue: row[index] ?? '',
-				};
-			});
-		});
-	}
-
 	parseDefinition(): SecondaryInstanceDefinition {
-		const csvData = this.resource.data.replace(/[\n\r]+$/, '');
-		const { columns, meta } = this.parseCSVHeader(csvData);
-		const { rows } = this.parseCSVRows(csvData, {
-			columns,
-			delimiter: meta.delimiter,
-		});
-		const items = this.toItems(columns, rows);
-
+		const items = parseItems(this.resourceURL, this.resource.data);
 		return csvExternalSecondaryInstanceDefinition(this.instanceId, items);
 	}
 }

package/src/parse/model/SecondaryInstance/sources/external-instance-csv-parser.ts

@@ -0,0 +1,185 @@
+import type { JRResourceURL } from '@getodk/common/jr-resources/JRResourceURL';
+import * as papa from 'papaparse';
+import { ErrorProductionDesignPendingError } from '../../../../error/ErrorProductionDesignPendingError';
+
+type CSVColumn = string;
+type CSVRow = readonly CSVColumn[];
+type AssertCSVRow = (resourceURL: JRResourceURL, columns: unknown) => asserts columns is CSVRow;
+
+interface ParsedCSVHeader {
+	readonly columns: CSVRow;
+	readonly errors: readonly [];
+	readonly meta: papa.ParseMeta;
+}
+
+interface ParseCSVOptions {
+	readonly columns: readonly string[];
+	readonly delimiter: string;
+}
+
+interface ParsedCSVRows {
+	readonly rows: readonly CSVRow[];
+	readonly errors: readonly [];
+	readonly meta: papa.ParseMeta;
+}
+
+interface CSVExternalSecondaryInstanceItemColumn {
+	readonly columnName: string;
+	readonly cellValue: string;
+}
+
+type CSVExternalSecondaryInstanceItem = readonly CSVExternalSecondaryInstanceItemColumn[];
+
+/**
+ * Based on {@link https://github.com/getodk/central-frontend/commit/29cebcc870c9be70ab0d222e3349e34639045d19}
+ *
+ * Central performs this check for header and rows. A comment is included there for the header check, but the logic is the same in both cases.
+ */
+const rejectNullCharacters = (resourceURL: JRResourceURL, cell: string) => {
+	if (cell.includes('\0')) {
+		throw new ErrorProductionDesignPendingError(
+			`Failed to parse CSV ${resourceURL.href}: null character`
+		);
+	}
+};
+
+const stripTrailingEmptyCells = (columns: CSVRow, row: CSVRow): CSVRow => {
+	const result = row.slice();
+
+	while (result.length > columns.length && result.at(-1) === '') {
+		result.pop();
+	}
+
+	return result;
+};
+
+const assertCSVRow: AssertCSVRow = (resourceURL: JRResourceURL, columns) => {
+	if (!Array.isArray(columns)) {
+		throw new ErrorProductionDesignPendingError(
+			`Failed to parse CSV ${resourceURL.href}: invalid columns`
+		);
+	}
+
+	for (const [index, column] of columns.entries()) {
+		if (typeof column !== 'string') {
+			throw new ErrorProductionDesignPendingError(
+				`Failed to parse CSV ${resourceURL.href}: invalid column at ${index}`
+			);
+		}
+
+		rejectNullCharacters(resourceURL, column);
+	}
+};
+
+type AssertPapaparseSuccess = (
+	resourceURL: JRResourceURL,
+	errors: readonly papa.ParseError[]
+) => asserts errors is readonly [];
+
+const assertPapaparseSuccess: AssertPapaparseSuccess = (resourceURL, errors) => {
+	if (errors.length > 0) {
+		const cause = new AggregateError(errors);
+		throw new ErrorProductionDesignPendingError(`Failed to parse CSV ${resourceURL.href}`, {
+			cause,
+		});
+	}
+};
+
+/**
+ * Largely based on {@link https://github.com/getodk/central-frontend/blob/42c9277709e593480d1462e28b4be5f1364532b7/src/util/csv.js#L170}
+ */
+const parseCSVRows = (
+	resourceURL: JRResourceURL,
+	csvData: string,
+	options: ParseCSVOptions
+): ParsedCSVRows => {
+	const { columns, delimiter } = options;
+	const { data, errors, meta } = papa.parse(csvData, {
+		delimiter,
+		download: false,
+	});
+
+	assertPapaparseSuccess(resourceURL, errors);
+
+	const rowData = data.slice(1);
+
+	const rows = rowData.map((values, index) => {
+		assertCSVRow(resourceURL, values);
+
+		const rowIndex = index + 1;
+
+		// Central: Remove trailing empty cells.
+		const row = stripTrailingEmptyCells(columns, values);
+
+		// Central: Throw if there are too many cells.
+		if (row.length > columns.length) {
+			throw new ErrorProductionDesignPendingError(
+				`Failed to parse CSV ${resourceURL.href}: row ${rowIndex}, expected ${columns.length} columns, got ${row.length}`
+			);
+		}
+
+		return row;
+	});
+
+	return {
+		errors,
+		meta,
+		rows,
+	};
+};
+
+const toItems = (
+	columns: CSVRow,
+	rows: readonly CSVRow[]
+): readonly CSVExternalSecondaryInstanceItem[] => {
+	return rows.map((row) => {
+		return columns.map((columnName, index) => {
+			return {
+				columnName,
+				cellValue: row[index] ?? '',
+			};
+		});
+	});
+};
+
+/**
+ * Based on
+ * {@link https://github.com/getodk/central-frontend/blob/42c9277709e593480d1462e28b4be5f1364532b7/src/util/csv.js#L79} (and {@link https://github.com/getodk/central-frontend/blob/42c9277709e593480d1462e28b4be5f1364532b7/src/util/csv.js#L13}).
+ *
+ * The most significant deviations at time of writing:
+ *
+ * - we have already retrieved the CSV resource, so we are parsing the raw CSV data directly.
+ * - we have no need for asynchronous/streaming parsing at this point in the
+ *   form initialization process, so we can dispense with those details of the
+ *   {@link papa | papaparse} API/config.
+ */
+const parseCSVHeader = (resourceURL: JRResourceURL, csvData: string): ParsedCSVHeader => {
+	const { data, errors, meta } = papa.parse(csvData, {
+		delimitersToGuess: [',', ';', '\t', '|'],
+		download: false,
+		preview: 1,
+	});
+	const [columns = []] = data;
+
+	assertCSVRow(resourceURL, columns);
+	assertPapaparseSuccess(resourceURL, errors);
+
+	return {
+		errors,
+		meta,
+		columns,
+	};
+};
+
+export const parseItems = (
+	resourceURL: JRResourceURL,
+	data: string
+): readonly CSVExternalSecondaryInstanceItem[] => {
+	const csvData = data.replace(/[\n\r]+$/, '');
+	const { columns, meta } = parseCSVHeader(resourceURL, csvData);
+	const { rows } = parseCSVRows(resourceURL, csvData, {
+		columns,
+		delimiter: meta.delimiter,
+	});
+	return toItems(columns, rows);
+};