@getodk/xforms-engine 0.3.0 → 0.5.0

package/src/parse/{NoteNodeDefinition.ts → model/NoteNodeDefinition.ts}

@@ -1,17 +1,17 @@
+import type { NoteNode } from '../../client/NoteNode.ts';
 import type { AnyBodyElementDefinition } from '../body/BodyDefinition.ts';
-import type { InputDefinition } from '../body/control/InputDefinition.ts';
-import type { NoteNode } from '../client/NoteNode.ts';
-import type { ConstantTruthyDependentExpression } from '../expression/DependentExpression.ts';
-import { BindComputation } from '../model/BindComputation.ts';
-import type { BindDefinition } from '../model/BindDefinition.ts';
-import { LeafNodeDefinition } from '../model/LeafNodeDefinition.ts';
-import type { ParentNodeDefinition } from '../model/NodeDefinition.ts';
-import type { HintDefinition } from './text/HintDefinition.ts';
-import type { LabelDefinition } from './text/LabelDefinition.ts';
+import type { InputControlDefinition } from '../body/control/InputControlDefinition.ts';
+import { BindComputationExpression } from '../expression/BindComputationExpression.ts';
+import type { ConstantTruthyDependentExpression } from '../expression/abstract/DependentExpression.ts';
+import type { HintDefinition } from '../text/HintDefinition.ts';
+import type { LabelDefinition } from '../text/LabelDefinition.ts';
+import type { BindDefinition } from './BindDefinition.ts';
+import { LeafNodeDefinition } from './LeafNodeDefinition.ts';
+import type { ParentNodeDefinition } from './NodeDefinition.ts';
 
 // prettier-ignore
 export type NoteReadonlyDefinition =
-	&	BindComputation<'readonly'>
+	&	BindComputationExpression<'readonly'>
 	& ConstantTruthyDependentExpression;
 
 export interface NoteBindDefinition extends BindDefinition {
@@ -31,7 +31,7 @@ export type NoteTextDefinition =
 /**
  * @package This class is used internally, both in static types and at runtime,
  * to guard and guide the distinction between instance state nodes for 'note'
- * and 'string' node types. It is intentionally package-private! The less
+ * and 'input' node types. It is intentionally package-private! The less
  * specific {@link NoteNode.definition} type, if it has any client value at all,
  * should be more than sufficient. Clients are otherwise expected to use other
  * aspects of the node's interface (such as its {@link NoteNode.nodeType} and
@@ -61,7 +61,7 @@ export class NoteNodeDefinition extends LeafNodeDefinition {
 	constructor(
 		parent: ParentNodeDefinition,
 		override readonly bind: NoteBindDefinition,
-		override readonly bodyElement: InputDefinition,
+		override readonly bodyElement: InputControlDefinition,
 		readonly noteTextDefinition: NoteTextDefinition,
 		node: Element
 	) {

package/src/{model → parse/model}/RepeatRangeDefinition.ts

@@ -1,5 +1,5 @@
 import type { RepeatElementDefinition } from '../body/RepeatElementDefinition.ts';
-import { RepeatCountControlExpression } from '../parse/expression/RepeatCountControlExpression.ts';
+import { RepeatCountControlExpression } from '../expression/RepeatCountControlExpression.ts';
 import type { BindDefinition } from './BindDefinition.ts';
 import { DescendentNodeDefinition } from './DescendentNodeDefinition.ts';
 import type { NodeDefinition, ParentNodeDefinition } from './NodeDefinition.ts';

package/src/{model → parse/model}/RootDefinition.ts

@@ -1,7 +1,7 @@
-import type { XFormDefinition } from '../XFormDefinition.ts';
 import type { BodyClassList } from '../body/BodyDefinition.ts';
-import { NoteNodeDefinition } from '../parse/NoteNodeDefinition.ts';
+import type { XFormDefinition } from '../XFormDefinition.ts';
 import type { BindDefinition } from './BindDefinition.ts';
+import type { FormSubmissionDefinition } from './FormSubmissionDefinition.ts';
 import { LeafNodeDefinition } from './LeafNodeDefinition.ts';
 import type { ModelDefinition } from './ModelDefinition.ts';
 import type {
@@ -9,6 +9,7 @@ import type {
 	NodeDefinition,
 	ParentNodeDefinition,
 } from './NodeDefinition.ts';
+import { NoteNodeDefinition } from './NoteNodeDefinition.ts';
 import { RepeatRangeDefinition } from './RepeatRangeDefinition.ts';
 import { SubtreeDefinition } from './SubtreeDefinition.ts';
 
@@ -26,11 +27,11 @@ export class RootDefinition implements NodeDefinition<'root'> {
 	readonly defaultValue = null;
 
 	readonly isTranslated = false;
-	readonly dependencyExpressions: ReadonlySet<string> = new Set<string>();
 
 	constructor(
 		protected readonly form: XFormDefinition,
 		protected readonly model: ModelDefinition,
+		readonly submission: FormSubmissionDefinition,
 		readonly classes: BodyClassList
 	) {
 		// TODO: theoretically the pertinent step in the bind's `nodeset` *could* be

package/src/parse/model/SecondaryInstance/SecondaryInstanceDefinition.ts

@@ -0,0 +1,4 @@
+import { StaticDocument } from '../../../integration/xpath/static-dom/StaticDocument.ts';
+import { SecondaryInstanceRootDefinition } from './SecondaryInstanceRootDefinition.ts';
+
+export class SecondaryInstanceDefinition extends StaticDocument<SecondaryInstanceRootDefinition> {}

package/src/parse/model/SecondaryInstance/SecondaryInstanceRootDefinition.ts

@@ -0,0 +1,12 @@
+import type { XFormsSecondaryInstanceElement } from '@getodk/xpath';
+import { XFORMS_KNOWN_ATTRIBUTE, XFORMS_LOCAL_NAME } from '@getodk/xpath';
+import { StaticElement } from '../../../integration/xpath/static-dom/StaticElement.ts';
+import type { SecondaryInstanceDefinition } from './SecondaryInstanceDefinition.ts';
+
+export class SecondaryInstanceRootDefinition
+	extends StaticElement<SecondaryInstanceDefinition>
+	implements XFormsSecondaryInstanceElement<StaticElement>
+{
+	override readonly [XFORMS_LOCAL_NAME] = 'instance';
+	override readonly [XFORMS_KNOWN_ATTRIBUTE] = 'id';
+}

package/src/parse/model/SecondaryInstance/SecondaryInstancesDefinition.ts

@@ -0,0 +1,102 @@
+import { JRResourceURL } from '@getodk/common/jr-resources/JRResourceURL.ts';
+import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
+import type { XFormsSecondaryInstanceMap } from '@getodk/xpath';
+import { ErrorProductionDesignPendingError } from '../../../error/ErrorProductionDesignPendingError.ts';
+import type { EngineXPathNode } from '../../../integration/xpath/adapter/kind.ts';
+import type { XFormDOM } from '../../XFormDOM.ts';
+import { SecondaryInstanceRootDefinition } from './SecondaryInstanceRootDefinition.ts';
+import { BlankSecondaryInstanceSource } from './sources/BlankSecondaryInstanceSource.ts';
+import { CSVExternalSecondaryInstanceSource } from './sources/CSVExternalSecondaryInstance.ts';
+import type { ExternalSecondaryInstanceResourceLoadOptions } from './sources/ExternalSecondaryInstanceResource.ts';
+import { ExternalSecondaryInstanceResource } from './sources/ExternalSecondaryInstanceResource.ts';
+import { GeoJSONExternalSecondaryInstanceSource } from './sources/GeoJSONExternalSecondaryInstance.ts';
+import { InternalSecondaryInstanceSource } from './sources/InternalSecondaryInstanceSource.ts';
+import type { SecondaryInstanceSource } from './sources/SecondaryInstanceSource.ts';
+import { XMLExternalSecondaryInstanceSource } from './sources/XMLExternalSecondaryInstanceSource.ts';
+
+export class SecondaryInstancesDefinition
+	extends Map<string, SecondaryInstanceRootDefinition>
+	implements XFormsSecondaryInstanceMap<EngineXPathNode>
+{
+	/**
+	 * @package Only to be used for testing
+	 */
+	static loadSync(xformDOM: XFormDOM): SecondaryInstancesDefinition {
+		const { secondaryInstanceElements } = xformDOM;
+		const sources = secondaryInstanceElements.map((domElement) => {
+			const instanceId = domElement.getAttribute('id');
+			const src = domElement.getAttribute('src');
+
+			if (src != null) {
+				throw new ErrorProductionDesignPendingError(
+					`Unexpected external secondary instance src attribute: ${src}`
+				);
+			}
+
+			return new InternalSecondaryInstanceSource(instanceId, src, domElement);
+		});
+
+		return new this(sources);
+	}
+
+	static async load(
+		xformDOM: XFormDOM,
+		options: ExternalSecondaryInstanceResourceLoadOptions
+	): Promise<SecondaryInstancesDefinition> {
+		const { secondaryInstanceElements } = xformDOM;
+
+		const sources = await Promise.all(
+			secondaryInstanceElements.map(async (domElement) => {
+				const instanceId = domElement.getAttribute('id');
+				const src = domElement.getAttribute('src');
+
+				if (src == null) {
+					return new InternalSecondaryInstanceSource(instanceId, src, domElement);
+				}
+
+				if (!JRResourceURL.isJRResourceReference(src)) {
+					throw new ErrorProductionDesignPendingError(
+						`Unexpected external secondary instance src attribute: ${src}`
+					);
+				}
+
+				const resourceURL = JRResourceURL.from(src);
+				const resource = await ExternalSecondaryInstanceResource.load(
+					instanceId,
+					resourceURL,
+					options
+				);
+
+				if (resource.isBlank) {
+					return new BlankSecondaryInstanceSource(instanceId, resourceURL, domElement);
+				}
+
+				switch (resource.format) {
+					case 'csv':
+						return new CSVExternalSecondaryInstanceSource(domElement, resource);
+
+					case 'geojson':
+						return new GeoJSONExternalSecondaryInstanceSource(domElement, resource);
+
+					case 'xml':
+						return new XMLExternalSecondaryInstanceSource(domElement, resource);
+
+					default:
+						throw new UnreachableError(resource);
+				}
+			})
+		);
+
+		return new this(sources);
+	}
+
+	private constructor(sources: readonly SecondaryInstanceSource[]) {
+		super(
+			sources.map((source) => {
+				const { root } = source.parseDefinition();
+
+				return [root.getAttributeValue('id'), root];
+			})
+		);
+	}
+}

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

@@ -0,0 +1,40 @@
+import { XFORMS_NAMESPACE_URI } from '@getodk/common/constants/xmlns.ts';
+import type { JRResourceURL } from '@getodk/common/jr-resources/JRResourceURL.ts';
+import type { StaticNode } from '../../../../integration/xpath/static-dom/StaticNode.ts';
+import { parseStaticDocumentFromDOMSubtree } from '../../../shared/parseStaticDocumentFromDOMSubtree.ts';
+import type { DOMSecondaryInstanceElement } from '../../../XFormDOM.ts';
+import { SecondaryInstanceDefinition } from '../SecondaryInstanceDefinition.ts';
+import { SecondaryInstanceRootDefinition } from '../SecondaryInstanceRootDefinition.ts';
+import { SecondaryInstanceSource } from './SecondaryInstanceSource.ts';
+
+export class BlankSecondaryInstanceSource extends SecondaryInstanceSource<'blank'> {
+	constructor(
+		instanceId: string,
+		resourceURL: JRResourceURL,
+		domElement: DOMSecondaryInstanceElement
+	) {
+		super('blank', instanceId, resourceURL, domElement);
+	}
+
+	/**
+	 * @todo there is really no sense in using the DOM for this, other than it was
+	 * quicker/more ergonomic than constructing the requisite {@link StaticNode}
+	 * structures directly. Pretty good sign those constructor signatures could
+	 * use some TLC!
+	 */
+	parseDefinition(): SecondaryInstanceDefinition {
+		const xmlDocument = this.domElement.ownerDocument.implementation.createDocument(
+			XFORMS_NAMESPACE_URI,
+			'instance'
+		);
+		const instanceElement = xmlDocument.documentElement;
+
+		instanceElement.setAttribute('id', this.instanceId);
+
+		return parseStaticDocumentFromDOMSubtree(
+			SecondaryInstanceDefinition,
+			SecondaryInstanceRootDefinition,
+			instanceElement
+		);
+	}
+}

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

@@ -0,0 +1,288 @@
+import { XFORMS_NAMESPACE_URI } from '@getodk/common/constants/xmlns.ts';
+import type { JRResourceURL } from '@getodk/common/jr-resources/JRResourceURL.ts';
+import * as papa from 'papaparse';
+import { ErrorProductionDesignPendingError } from '../../../../error/ErrorProductionDesignPendingError.ts';
+import { StaticAttribute } from '../../../../integration/xpath/static-dom/StaticAttribute.ts';
+import { StaticElement } from '../../../../integration/xpath/static-dom/StaticElement.ts';
+import { StaticText } from '../../../../integration/xpath/static-dom/StaticText.ts';
+import { SecondaryInstanceDefinition } from '../SecondaryInstanceDefinition.ts';
+import { SecondaryInstanceRootDefinition } from '../SecondaryInstanceRootDefinition.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;
+}
+
+type CSVExternalSecondaryInstanceItem = readonly CSVExternalSecondaryInstanceItemColumn[];
+
+class CSVExternalSecondaryInstanceColumnElement extends StaticElement {
+	constructor(parent: StaticElement, column: CSVExternalSecondaryInstanceItemColumn) {
+		const { columnName, cellValue } = column;
+
+		super(
+			parent,
+			() => [],
+			(self) => [new StaticText(self, cellValue)],
+			{
+				namespaceURI: XFORMS_NAMESPACE_URI,
+				localName: columnName,
+			}
+		);
+	}
+}
+
+class CSVExternalSecondaryInstanceItemElement extends StaticElement {
+	constructor(parent: StaticElement, item: CSVExternalSecondaryInstanceItem) {
+		super(
+			parent,
+			() => [],
+			(self) => {
+				return item.map((column) => {
+					return new CSVExternalSecondaryInstanceColumnElement(self, column);
+				});
+			},
+			{
+				namespaceURI: XFORMS_NAMESPACE_URI,
+				localName: 'item',
+			}
+		);
+	}
+}
+
+class CSVExternalSecondaryInstanceRootElement extends StaticElement {
+	constructor(parent: StaticElement, items: readonly CSVExternalSecondaryInstanceItem[]) {
+		super(
+			parent,
+			() => [],
+			(self) => {
+				return items.map((item) => {
+					return new CSVExternalSecondaryInstanceItemElement(self, item);
+				});
+			},
+			{
+				namespaceURI: XFORMS_NAMESPACE_URI,
+				localName: 'root',
+			}
+		);
+	}
+}
+
+class CSVExternalSecondaryInstanceDocumentElement extends SecondaryInstanceRootDefinition {
+	constructor(
+		instanceId: string,
+		parent: CSVExternalSecondaryInstanceDefinition,
+		items: readonly CSVExternalSecondaryInstanceItem[]
+	) {
+		super(
+			parent,
+			(self) => [
+				new StaticAttribute(self, {
+					namespaceURI: XFORMS_NAMESPACE_URI,
+					localName: 'id',
+					value: instanceId,
+				}),
+			],
+			(self) => [new CSVExternalSecondaryInstanceRootElement(self, items)],
+			{
+				namespaceURI: XFORMS_NAMESPACE_URI,
+				localName: 'instance',
+			}
+		);
+	}
+}
+
+class CSVExternalSecondaryInstanceDefinition extends SecondaryInstanceDefinition {
+	constructor(instanceId: string, items: readonly CSVExternalSecondaryInstanceItem[]) {
+		super((self) => {
+			return new CSVExternalSecondaryInstanceDocumentElement(instanceId, self, items);
+		});
+	}
+}
+
+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);
+
+		return new CSVExternalSecondaryInstanceDefinition(this.instanceId, items);
+	}
+}