@getodk/xforms-engine 0.4.0 → 0.6.0

package/src/parse/model/RangeNodeDefinition.ts

@@ -0,0 +1,118 @@
+import type { ValueType } from '../../client/ValueType.ts';
+import { ErrorProductionDesignPendingError } from '../../error/ErrorProductionDesignPendingError.ts';
+import type { RuntimeValue, SharedValueCodec } from '../../lib/codecs/getSharedValueCodec.ts';
+import { getSharedValueCodec } from '../../lib/codecs/getSharedValueCodec.ts';
+import type {
+	RangeControlBoundsDefinition,
+	RangeControlDefinition,
+} from '../body/control/RangeControlDefinition.ts';
+import type { BindDefinition } from './BindDefinition.ts';
+import { LeafNodeDefinition } from './LeafNodeDefinition.ts';
+import type { ParentNodeDefinition } from './NodeDefinition.ts';
+
+const RANGE_VALUE_TYPES = ['decimal', 'int'] as const;
+
+export type RangeValueType = (typeof RANGE_VALUE_TYPES)[number];
+
+type AssertedRangeValueType<V extends ValueType> = Extract<V, RangeValueType>;
+
+type AssertRangeBindDefinition = <V extends ValueType>(
+	bind: BindDefinition<V>
+) => asserts bind is BindDefinition<AssertedRangeValueType<V>>;
+
+const assertRangeBindDefinition: AssertRangeBindDefinition = (bind) => {
+	if (!RANGE_VALUE_TYPES.includes(bind.type.resolved as RangeValueType)) {
+		throw new ErrorProductionDesignPendingError(
+			`Expected range to have bind type "decimal" or "int", got: ${bind.type.resolved}`
+		);
+	}
+};
+
+export interface RangeLeafNodeDefinition<V extends ValueType = ValueType>
+	extends LeafNodeDefinition<V> {
+	readonly bodyElement: RangeControlDefinition;
+}
+
+const decodeBoundsValue = <V extends ValueType>(
+	codec: SharedValueCodec<V>,
+	value: string
+): NonNullable<RuntimeValue<V>> => {
+	const decoded = codec.decodeValue(value);
+
+	if (decoded == null) {
+		throw new ErrorProductionDesignPendingError(
+			`Failed to decode bounds value (encoded as ${JSON.stringify(value)})`
+		);
+	}
+
+	return decoded;
+};
+
+class RangeNodeBoundsDefinition<V extends RangeValueType = RangeValueType> {
+	static from<V extends RangeValueType>(
+		bounds: RangeControlBoundsDefinition,
+		bind: BindDefinition<V>
+	): RangeNodeBoundsDefinition<V> {
+		const type = bind.type.resolved;
+		const codec = getSharedValueCodec(type);
+		const min = decodeBoundsValue(codec, bounds.start);
+		const max = decodeBoundsValue(codec, bounds.end);
+		const step = decodeBoundsValue(codec, bounds.step);
+
+		return new this(min, max, step);
+	}
+
+	constructor(
+		readonly min: NonNullable<RuntimeValue<V>>,
+		readonly max: NonNullable<RuntimeValue<V>>,
+		readonly step: NonNullable<RuntimeValue<V>>
+	) {}
+}
+
+/**
+ * @todo We should really consider making `LeafNodeDefinition` an abstract base
+ * class, and each node's definition an explicit concrete subclass of that. It
+ * would simplify a lot of things, reduce redundancy (and drift!) between
+ * various like `*Definition` types, and allow us to reason more clearly about
+ * what parse-product-input is used to construct each primary instance node.
+ * Furthermore, it would give us a great deal more flexibility to revisit some
+ * of the weaker parts of our current data model (e.g. splitting up selects).
+ *
+ * I explored this refactor as part of the prerequisite work to support range
+ * controls. I eventually backed out because it involved more churn than I felt
+ * comfortable with, but I do think we should keep an eye out for other
+ * opportunities to take on the churn.
+ */
+export class RangeNodeDefinition<V extends RangeValueType = RangeValueType>
+	extends LeafNodeDefinition<V>
+	implements RangeLeafNodeDefinition<V>
+{
+	static from<V extends ValueType>(
+		parent: ParentNodeDefinition,
+		bind: BindDefinition<V>,
+		bodyElement: RangeControlDefinition,
+		node: Element
+	): RangeNodeDefinition<Extract<V, RangeValueType>> {
+		assertRangeBindDefinition(bind);
+
+		return new this(parent, bind, bodyElement, node);
+	}
+
+	readonly bounds: RangeNodeBoundsDefinition<V>;
+
+	private constructor(
+		parent: ParentNodeDefinition,
+		override readonly bind: BindDefinition<V>,
+		override readonly bodyElement: RangeControlDefinition,
+		node: Element
+	) {
+		super(parent, bind, bodyElement, node);
+
+		this.bounds = RangeNodeBoundsDefinition.from(bodyElement.bounds, bind);
+	}
+}
+
+// prettier-ignore
+export type AnyRangeNodeDefinition =
+	| RangeNodeDefinition<'decimal'>
+	| RangeNodeDefinition<'int'>;

package/src/parse/model/RepeatInstanceDefinition.ts

@@ -1,15 +1,18 @@
+import { NamespaceDeclarationMap } from '../../lib/names/NamespaceDeclarationMap.ts';
+import { QualifiedName } from '../../lib/names/QualifiedName.ts';
 import { RepeatElementDefinition } from '../body/RepeatElementDefinition.ts';
 import { DescendentNodeDefinition } from './DescendentNodeDefinition.ts';
-import type { ChildNodeDefinition, NodeDefinition } from './NodeDefinition.ts';
+import type { ChildNodeDefinition } from './NodeDefinition.ts';
 import type { AnyRepeatRangeDefinition } from './RepeatRangeDefinition.ts';
 
-export class RepeatInstanceDefinition
-	extends DescendentNodeDefinition<'repeat-instance', RepeatElementDefinition>
-	implements NodeDefinition<'repeat-instance'>
-{
+export class RepeatInstanceDefinition extends DescendentNodeDefinition<
+	'repeat-instance',
+	RepeatElementDefinition
+> {
 	readonly type = 'repeat-instance';
 
-	readonly nodeName: string;
+	readonly namespaceDeclarations: NamespaceDeclarationMap;
+	readonly qualifiedName: QualifiedName;
 	readonly children: readonly ChildNodeDefinition[];
 	readonly instances = null;
 	readonly defaultValue = null;
@@ -22,7 +25,8 @@ export class RepeatInstanceDefinition
 
 		super(parent, bind, bodyElement);
 
-		this.nodeName = range.nodeName;
+		this.qualifiedName = new QualifiedName(node);
+		this.namespaceDeclarations = new NamespaceDeclarationMap(this);
 		this.children = root.buildSubtree(this);
 	}
 

package/src/parse/model/RepeatRangeDefinition.ts

@@ -1,8 +1,10 @@
+import { NamespaceDeclarationMap } from '../../lib/names/NamespaceDeclarationMap.ts';
+import { QualifiedName } from '../../lib/names/QualifiedName.ts';
 import type { RepeatElementDefinition } from '../body/RepeatElementDefinition.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';
+import type { ParentNodeDefinition } from './NodeDefinition.ts';
 import { RepeatInstanceDefinition } from './RepeatInstanceDefinition.ts';
 import { RepeatTemplateDefinition } from './RepeatTemplateDefinition.ts';
 
@@ -29,10 +31,10 @@ const assertRepeatRangeDefinitionUnion: AssertRepeatRangeDefinitionUnion = (_def
 	// tautologically true!
 };
 
-export class RepeatRangeDefinition
-	extends DescendentNodeDefinition<'repeat-range', RepeatElementDefinition>
-	implements NodeDefinition<'repeat-range'>
-{
+export class RepeatRangeDefinition extends DescendentNodeDefinition<
+	'repeat-range',
+	RepeatElementDefinition
+> {
 	static from(
 		parent: ParentNodeDefinition,
 		bind: BindDefinition,
@@ -54,7 +56,8 @@ export class RepeatRangeDefinition
 	readonly count: RepeatCountControlExpression | null;
 
 	readonly node = null;
-	readonly nodeName: string;
+	readonly namespaceDeclarations: NamespaceDeclarationMap;
+	readonly qualifiedName: QualifiedName;
 	readonly defaultValue = null;
 
 	private constructor(
@@ -68,7 +71,8 @@ export class RepeatRangeDefinition
 		const { template, instanceNodes } = RepeatTemplateDefinition.parseModelNodes(this, modelNodes);
 
 		this.template = template;
-		this.nodeName = template.nodeName;
+		this.qualifiedName = template.qualifiedName;
+		this.namespaceDeclarations = new NamespaceDeclarationMap(this);
 		this.count = RepeatCountControlExpression.from(bodyElement, instanceNodes.length);
 
 		assertRepeatRangeDefinitionUnion(this);

package/src/parse/model/RepeatTemplateDefinition.ts

@@ -1,8 +1,10 @@
 import { JAVAROSA_NAMESPACE_URI } from '@getodk/common/constants/xmlns.ts';
+import { NamespaceDeclarationMap } from '../../lib/names/NamespaceDeclarationMap.ts';
+import { QualifiedName } from '../../lib/names/QualifiedName.ts';
 import type { RepeatElementDefinition } from '../body/RepeatElementDefinition.ts';
 import { BindDefinition } from './BindDefinition.ts';
 import { DescendentNodeDefinition } from './DescendentNodeDefinition.ts';
-import type { ChildNodeDefinition, NodeDefinition } from './NodeDefinition.ts';
+import type { ChildNodeDefinition } from './NodeDefinition.ts';
 import type { RepeatRangeDefinition } from './RepeatRangeDefinition.ts';
 
 const repeatTemplates = new WeakMap<BindDefinition, RepeatTemplateDefinition>();
@@ -72,10 +74,10 @@ interface ParsedRepeatNodes {
 	readonly instanceNodes: readonly Element[];
 }
 
-export class RepeatTemplateDefinition
-	extends DescendentNodeDefinition<'repeat-template', RepeatElementDefinition>
-	implements NodeDefinition<'repeat-template'>
-{
+export class RepeatTemplateDefinition extends DescendentNodeDefinition<
+	'repeat-template',
+	RepeatElementDefinition
+> {
 	static parseModelNodes(
 		range: RepeatRangeDefinition,
 		modelNodes: readonly [Element, ...Element[]]
@@ -115,7 +117,8 @@ export class RepeatTemplateDefinition
 	readonly type = 'repeat-template';
 
 	readonly node: Element;
-	readonly nodeName: string;
+	readonly namespaceDeclarations: NamespaceDeclarationMap;
+	readonly qualifiedName: QualifiedName;
 	readonly children: readonly ChildNodeDefinition[];
 	readonly instances = null;
 	readonly defaultValue = null;
@@ -133,7 +136,8 @@ export class RepeatTemplateDefinition
 		node.removeAttributeNS(JAVAROSA_NAMESPACE_URI, 'template');
 
 		this.node = node;
-		this.nodeName = node.localName;
+		this.qualifiedName = new QualifiedName(node);
+		this.namespaceDeclarations = new NamespaceDeclarationMap(this);
 		this.children = root.buildSubtree(this);
 	}
 

package/src/parse/model/RootAttributeDefinition.ts

@@ -0,0 +1,45 @@
+import { XMLNS_NAMESPACE_URI } from '@getodk/common/constants/xmlns.ts';
+import type { NamedNodeDefinition } from '../../lib/names/NamespaceDeclarationMap.ts';
+import { QualifiedName } from '../../lib/names/QualifiedName.ts';
+import { escapeXMLText } from '../../lib/xml-serialization.ts';
+import type { RootDefinition } from './RootDefinition.ts';
+
+interface RootAttributeSource {
+	readonly namespaceURI: string | null;
+	readonly nodeName: string;
+	readonly prefix: string | null;
+	readonly localName: string;
+	readonly value: string;
+}
+
+/**
+ * @todo This class is named and typed to emphasize its intentionally narrow
+ * usage and purpose. It **intentionally** avoids addressing the much broader
+ * set of concerns around modeling attributes in primary instance/submissions.
+ */
+export class RootAttributeDefinition implements NamedNodeDefinition {
+	private readonly serializedXML: string;
+
+	readonly parent: RootDefinition;
+	readonly qualifiedName: QualifiedName;
+	readonly value: string;
+
+	constructor(root: RootDefinition, source: RootAttributeSource) {
+		const { namespaceURI, nodeName, value } = source;
+
+		this.parent = root;
+		this.qualifiedName = new QualifiedName(source);
+		this.value = value;
+
+		// We serialize namespace declarations separately
+		if (namespaceURI === XMLNS_NAMESPACE_URI) {
+			this.serializedXML = '';
+		} else {
+			this.serializedXML = ` ${nodeName}="${escapeXMLText(value, true)}"`;
+		}
+	}
+
+	serializeAttributeXML(): string {
+		return this.serializedXML;
+	}
+}

package/src/parse/model/RootAttributeMap.ts

@@ -0,0 +1,44 @@
+import { XMLNS_NAMESPACE_URI } from '@getodk/common/constants/xmlns.ts';
+import type { QualifiedName } from '../../lib/names/QualifiedName.ts';
+import { RootAttributeDefinition } from './RootAttributeDefinition.ts';
+import type { RootDefinition } from './RootDefinition.ts';
+
+const isNonNamespaceDeclarationDOMAttr = (domAttr: Attr) => {
+	return domAttr.namespaceURI !== XMLNS_NAMESPACE_URI;
+};
+
+/**
+ * @todo This can be trivially expanded to a narrowly general case when we
+ * prioritize work to
+ * {@link https://github.com/getodk/web-forms/issues/285 | support attributes}
+ * (as modeled form nodes on par with elements). It's been deferred here to
+ * avoid expanding scope of an already fairly large yak shave.
+ *
+ * @todo There's a **much more expansive** general case just waiting for a good
+ * opportuntity to prioritize it. E.g. a `NamedNodeMap<T>`, where T is any
+ * generalized concept of a named node. This expansive generalization would have
+ * a ton of value in a variety of known performance optimization
+ * targets/solutions (i.e. optimizing the most redundant, suboptimal, frequently
+ * performed aspects of any typical XPath expression in a typical XForm).
+ *
+ * @see {@link QualifiedName} for more detail.
+ */
+export class RootAttributeMap extends Map<QualifiedName, RootAttributeDefinition> {
+	static from(root: RootDefinition, domRootSourceElement: Element) {
+		const domAttrs = Array.from(domRootSourceElement.attributes);
+		const nonNamespaceDeclarationDOMAttrs = domAttrs.filter(isNonNamespaceDeclarationDOMAttr);
+		const attributes = nonNamespaceDeclarationDOMAttrs.map((source) => {
+			return new RootAttributeDefinition(root, source);
+		});
+
+		return new this(attributes);
+	}
+
+	private constructor(attributes: readonly RootAttributeDefinition[]) {
+		super(
+			attributes.map((attribute) => {
+				return [attribute.qualifiedName, attribute];
+			})
+		);
+	}
+}

package/src/parse/model/RootDefinition.ts

@@ -1,61 +1,59 @@
+import { NamespaceDeclarationMap } from '../../lib/names/NamespaceDeclarationMap.ts';
+import { QualifiedName } from '../../lib/names/QualifiedName.ts';
 import type { BodyClassList } from '../body/BodyDefinition.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 {
-	ChildNodeDefinition,
-	NodeDefinition,
-	ParentNodeDefinition,
-} from './NodeDefinition.ts';
+import type { ChildNodeDefinition, ParentNodeDefinition } from './NodeDefinition.ts';
+import { NodeDefinition } from './NodeDefinition.ts';
 import { NoteNodeDefinition } from './NoteNodeDefinition.ts';
+import { RangeNodeDefinition } from './RangeNodeDefinition.ts';
 import { RepeatRangeDefinition } from './RepeatRangeDefinition.ts';
+import { RootAttributeMap } from './RootAttributeMap.ts';
 import { SubtreeDefinition } from './SubtreeDefinition.ts';
 
-export class RootDefinition implements NodeDefinition<'root'> {
+export class RootDefinition extends NodeDefinition<'root'> {
 	readonly type = 'root';
-	readonly bind: BindDefinition;
-	readonly nodeset: string;
-	readonly nodeName: string;
+	readonly qualifiedName: QualifiedName;
 	readonly bodyElement = null;
 	readonly root = this;
 	readonly parent = null;
+	readonly namespaceDeclarations: NamespaceDeclarationMap;
+	readonly attributes: RootAttributeMap;
 	readonly children: readonly ChildNodeDefinition[];
 	readonly instances = null;
 	readonly node: Element;
 	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
 	) {
+		const { primaryInstanceRoot } = form.xformDOM;
+		const qualifiedName = new QualifiedName(primaryInstanceRoot);
+		const nodeName = qualifiedName.getPrefixedName();
+
 		// TODO: theoretically the pertinent step in the bind's `nodeset` *could* be
 		// namespaced. It also may make more sense to determine the root nodeset
 		// earlier (i.e. in the appropriate definition class).
-		//
-		// TODO: while it's unlikely a form actually defines a <bind> for the root,
-		// if it did, bind nodesets are not yet normalized, so `/root` may currently
-		// be defined as `/ root` (or even `/ *` or any other valid expression
-		// resolving to the root).
-		const { primaryInstanceRoot } = form.xformDOM;
-		const { localName: rootNodeName } = primaryInstanceRoot;
-
-		this.nodeName = rootNodeName;
-
-		const nodeset = `/${rootNodeName}`;
+		const nodeset = `/${nodeName}`;
 		const bind = model.binds.get(nodeset);
 
 		if (bind == null) {
 			throw new Error('Missing root node bind definition');
 		}
 
-		this.bind = bind;
-		this.nodeset = nodeset;
+		super(bind);
+
+		this.qualifiedName = qualifiedName;
 		this.node = primaryInstanceRoot;
+		this.attributes = RootAttributeMap.from(this, primaryInstanceRoot);
+		this.namespaceDeclarations = new NamespaceDeclarationMap(this);
 		this.children = this.buildSubtree(this);
 	}
 
@@ -69,13 +67,13 @@ export class RootDefinition implements NodeDefinition<'root'> {
 		const childrenByName = new Map<string, [Element, ...Element[]]>();
 
 		for (const child of node.children) {
-			const { localName } = child;
+			const { nodeName } = child;
 
-			let elements = childrenByName.get(localName);
+			let elements = childrenByName.get(nodeName);
 
 			if (elements == null) {
 				elements = [child];
-				childrenByName.set(localName, elements);
+				childrenByName.set(nodeName, elements);
 			} else {
 				// TODO: check if previous element exists, was it previous element
 				// sibling. Highly likely this should otherwise fail!
@@ -83,8 +81,8 @@ export class RootDefinition implements NodeDefinition<'root'> {
 			}
 		}
 
-		return Array.from(childrenByName).map(([localName, children]) => {
-			const nodeset = `${parentNodeset}/${localName}`;
+		return Array.from(childrenByName).map(([nodeName, children]) => {
+			const nodeset = `${parentNodeset}/${nodeName}`;
 			const bind = binds.getOrCreateBindDefinition(nodeset);
 			const bodyElement = body.getBodyElement(nodeset);
 			const [firstChild, ...restChildren] = children;
@@ -101,6 +99,10 @@ export class RootDefinition implements NodeDefinition<'root'> {
 			const isLeafNode = element.childElementCount === 0;
 
 			if (isLeafNode) {
+				if (bodyElement?.type === 'range') {
+					return RangeNodeDefinition.from(parent, bind, bodyElement, element);
+				}
+
 				return (
 					NoteNodeDefinition.from(parent, bind, bodyElement, element) ??
 					new LeafNodeDefinition(parent, bind, bodyElement, element)

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
+		);
+	}
+}