@getodk/xforms-engine 0.6.0 → 0.8.0

package/src/parse/model/RepeatDefinition.ts

@@ -0,0 +1,382 @@
+import { JAVAROSA_NAMESPACE_URI } from '@getodk/common/constants/xmlns.ts';
+import type { XFORMS_KNOWN_ATTRIBUTE } from '@getodk/xpath';
+import type { RepeatRange } from '../../instance/hierarchy.ts';
+import type { PrimaryInstance } from '../../instance/PrimaryInstance.ts';
+import type { RepeatInstance } from '../../instance/repeat/RepeatInstance.ts';
+import type {
+	StaticAttribute,
+	StaticAttributeOptions,
+} from '../../integration/xpath/static-dom/StaticAttribute.ts';
+import { StaticDocument } from '../../integration/xpath/static-dom/StaticDocument.ts';
+import type {
+	StaticElement,
+	StaticElementOptions,
+} from '../../integration/xpath/static-dom/StaticElement.ts';
+import type { StaticNode } from '../../integration/xpath/static-dom/StaticNode.ts';
+import type { StaticText } from '../../integration/xpath/static-dom/StaticText.ts';
+import { NamespaceDeclarationMap } from '../../lib/names/NamespaceDeclarationMap.ts';
+import type { NamespaceURL } from '../../lib/names/NamespaceURL.ts';
+import type { QualifiedName, QualifiedNameSource } 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 { ChildNodeDefinition, ParentNodeDefinition } from './NodeDefinition.ts';
+import type { RootDefinition } from './RootDefinition.ts';
+import type { SubtreeDefinition } from './SubtreeDefinition.ts';
+
+interface JavaRosaNamespaceURI extends NamespaceURL {
+	readonly href: JAVAROSA_NAMESPACE_URI;
+}
+
+interface JRTemplateAttributeName extends QualifiedName {
+	readonly namespaceURI: JavaRosaNamespaceURI;
+	readonly localName: 'template';
+}
+
+const isJRTemplateAttributeName = (name: QualifiedNameSource) => {
+	if (name.localName !== 'template') {
+		return false;
+	}
+
+	const namespaceURI = (name.namespaceURI as NamespaceURL)?.href ?? name.namespaceURI;
+
+	return namespaceURI === JAVAROSA_NAMESPACE_URI;
+};
+
+interface JRTemplateAttribute extends StaticAttribute {
+	readonly qualifiedName: JRTemplateAttributeName;
+}
+
+const isJRTemplateAttribute = (attribute: StaticAttribute): attribute is JRTemplateAttribute => {
+	return isJRTemplateAttributeName(attribute.qualifiedName);
+};
+
+interface ExplicitRepeatTemplateElement extends StaticElement {
+	readonly [XFORMS_KNOWN_ATTRIBUTE]: 'template';
+
+	getAttributeValue(localName: 'template'): string;
+	getAttributeValue(localName: string): string | null;
+}
+
+/**
+ * Determines whether a model instance node is an **explicit** repeat template,
+ * as defined by the presence of a `jr:template` attribute on that node.
+ *
+ * @see {@link https://getodk.github.io/xforms-spec/#default-values-in-repeats}
+ */
+const isExplicitRepeatTemplateElement = (
+	sourceElement: StaticElement
+): sourceElement is ExplicitRepeatTemplateElement => {
+	return sourceElement.attributes.some(isJRTemplateAttribute);
+};
+
+const cloneStaticAttributeOptions = (attribute: StaticAttribute): StaticAttributeOptions => {
+	return {
+		name: attribute.qualifiedName,
+		value: attribute.value,
+	};
+};
+
+interface ClonedSubtreeStructure extends StaticElementOptions {
+	readonly attributes: readonly StaticAttributeOptions[];
+	readonly children: readonly StaticElementOptions[];
+}
+
+const cloneStaticSubtreeStructure = (sourceElement: StaticElement): ClonedSubtreeStructure => {
+	const name = sourceElement.qualifiedName;
+	const attributes = sourceElement.attributes.map(cloneStaticAttributeOptions);
+	const children = sourceElement.childElements.map(cloneStaticSubtreeStructure);
+
+	return {
+		name,
+		attributes,
+		children,
+	};
+};
+
+/**
+ * Clones the **structure** of a {@link StaticElement}, omitting
+ * {@link StaticText | text values} of the element itself, and any of its
+ * descendants.
+ *
+ * @todo This function's behavior is **plausibly** general purpose. The function
+ * itself, its argument, its local bindings are all named to reflect that fact.
+ *
+ * However, the **use case** for the function is quite specific: when a form
+ * defines a `<repeat>` that isn't associated with an explicit `jr:template`, we
+ * fabricate a template by cloning its structure with all text values removed
+ * (described in more detail for {@link parseRepeatTemplateElement}).
+ *
+ * As generalized as this the function is, it's not at all clear how or why we'd
+ * use it for other purposes. Even the top-of-mind (at time of writing) use case
+ * which might semantically line up with it (i.e. potentially as a basis to
+ * reconcile edit instance state into a form definition, as sort of a three-way
+ * merge) would effectively be pure overhead. For now, we have something
+ * library-ish living here private in this module unless/until we find another
+ * good reason to use it elsewhere!
+ *
+ * If we do find another plausible use case for this behavior, it's pretty
+ * likely we'd want to implement it as a part of the {@link StaticElement} (or
+ * somewhere else up the class hierarchy to {@link StaticNode}), to encapsulate
+ * as much as possible about how it's done. We've been pretty aggressive about
+ * changing the internals and signatures of {@link StaticNode}s and the
+ * static-dom abstraction. It'd be nice if ongoing changes were a lot more
+ * isolated, with far less impact on the growing set of use cases actually
+ * consuming the abstraction.
+ */
+const cloneStaticElementStructure = (sourceElement: StaticElement): StaticElement => {
+	const { root: clone } = new StaticDocument({
+		documentRoot: cloneStaticSubtreeStructure(sourceElement),
+		nodesetPrefix: sourceElement.parent.nodeset,
+	});
+
+	return clone;
+};
+
+export type RepeatInstanceNodes = readonly [StaticElement, ...StaticElement[]];
+
+/**
+ * Produces a consistent "repeat template" interface for each
+ * {@link RepeatDefinition}, which is used to produce new repeat instances in
+ * {@link PrimaryInstance | runtime form instance state}. How a "repeat
+ * template" is parsed is as follows:
+ *
+ * - If the form definition includes an **explicit template** (as described by
+ *   {@link isExplicitRepeatTemplateElement}) as the
+ *   {@link firstRepeatInstanceNode | first} node referenced by a `<repeat
+ *   nodeset>`, that node is returned as it was already parsed.
+ *
+ * - If the {@link firstRepeatInstanceNode | first} repeat instance node is
+ *   **NOT** an explicit template, a template is **implicitly created** from its
+ *   blank structure, as a
+ *   {@link cloneStaticElementStructure | clone of its structure}.
+ *
+ * The latter behavior may sound surprising if unfamiliar, but it is well
+ * understood. It is also known to be consistent with Collect (JavaRosa), as
+ * demonstrated by affected tests in `@getodk/scenario` which fail when this
+ * behavior is changed.
+ *
+ * - - -
+ *
+ * Note: this is a vastly simplified evolution of what was previously
+ * implemented in
+ * {@link https://github.com/getodk/web-forms/blob/99295eb1d6ec78cd6a758385793e97859b6a74cc/packages/xforms-engine/src/parse/model/RepeatTemplateDefinition.ts#L81 | `RepeatTemplateDefinition.parseModelNodes`}
+ * (permalink to implementation at time of writing/refactor).
+ *
+ * That previous implementation was based on a flawed mental model of how a
+ * parsed form model relates to the form's instance structure. The following
+ * describes the previous flawed mental model, and the reasoning behind revising
+ * the mental model established here.
+ *
+ * - - -
+ *
+ * **Flawed mental model**
+ *
+ * Repeat model definitions were composed of a combination of:
+ *
+ * 1. `RepeatRangeDefinition`: this effectively had a 1:1 correspondence to the
+ *    `<repeat>` _body element_ referencing the `nodeset` of 1+ instance nodes
+ *    (as defined in the form's model).
+ *
+ * 2. `RepeatTemplateDefinition`: this had a 0-1:1 correspondence between an
+ *    instance node (as defined in the form's model) defining a `jr:template`
+ *    attribute, if one exists; if none exists, one was synthesized at parse
+ *    time.
+ *
+ * 3. `RepeatInstanceDefinition`: these had an N:N correspondence to _every
+ *    non-template instance node_ (as defined in the form's model).
+ *
+ * For each instance of a form:
+ *
+ * - `RepeatRangeControlled` or `RepeatRangeUncontrolled` (engine-internal
+ *   implementation of the `RepeatRangeControlledNode` and
+ *   `RepeatRangeUncontrolledNode` client interfaces, respectively) also
+ *   corresponded 1:1 with a `RepeatRangeDefinition`.
+ *
+ * - `RepeatInstance` (engine-internal implementation of the
+ *   `RepeatInstanceNode`) had an N:N relationship with _either_:
+ *   - `RepeatInstanceDefinition`, if one was defined for that repeat instance's
+ *     the positional index
+ *   - `RepeatTemplateDefinition`, otherwise
+ *
+ * **Revised mental model**
+ *
+ * 1. `RepeatDefinition`: merges the responsibilities of the former
+ *    `RepeatRangeDefinition` and `RepeatTemplateDefinition`.
+ *
+ * 2. Repeat instance nodes (as defined in the form's model) are refereced
+ *    _during the construction of instance state_ (`PrimaryInstance`):
+ *
+ *   - if an instance node exists at the positional index of the
+ *     `RepeatInstance` to be created, that node is used to populate the
+ *     `RepeatInstance`'s initial state
+ *
+ *   - if no instance node exists at that positional index, the template
+ *     returned by {@link RepeatTemplateDefinition.parseRepeatTemplateElement}
+ *     is referenced for the `RepeatInstance`'s initial state instead
+ *
+ * Aside from simplifying the parsing responsibilities associated with repeats,
+ * this also creates a roughly 1:1 relationship between the different
+ * representations of what we call an "instance node".
+ *
+ * @todo The above "revised mental model" for repeat definitions pretty much
+ * reflects the same principles which will be applied for non-form instance
+ * state, i.e. for (a) restoring previously serialized instance state and/or (b)
+ * editing previously submitted instance state. It will make sense to reflect
+ * that once that aspect of implementation is complete!
+ *
+ * - - -
+ *
+ * At time of writing, I believe that detailing the differences between these
+ * mental models will provide useful context, in the long term, for reasoning
+ * about the relationship between "node definition" and "instance node" (as
+ * defined in a form or a serialized and/or submitted instance; also the
+ * engine's active, stateful representations of those same nodes).
+ *
+ * Namely, the revised relationship is _1 (node definition) : N (instance
+ * node)_, associated by each instance node's nodeset.
+ */
+const parseRepeatTemplateElement = (firstRepeatInstanceNode: StaticElement) => {
+	if (isExplicitRepeatTemplateElement(firstRepeatInstanceNode)) {
+		return firstRepeatInstanceNode;
+	}
+
+	return cloneStaticElementStructure(firstRepeatInstanceNode);
+
+	// TODO: We previously **intended** to check for duplicate explicit repeat
+	// templates (i.e. defined with a `jr:template` attribute). This was
+	// **partially** handled by defining a (temporary/local) mapping from the
+	// repeat's `BindDefinition` to an already-parsed explicit template element
+	// (if any). Identifying duplicates **should** have been handled by
+	// determining that an entry for the same binding already existed. **BUT NO
+	// ENTRY WAS NEVER WRITTEN!** This comment is now intended to recognize:
+	//
+	// 1. ... that the intended behavior was never implemented correctly in the
+	//    first place, and we are not making any changes to that intended aspect
+	//    of engine behavior/semantics by eliminating the flawed implementation
+	//    now.
+	//
+	// 2. ... that whether this behavior should have even been implemented was
+	//    also an open question! The previous text of this
+	//    comment's conceptual successor is preserved below, either for clarity in review or for logner-term posterity.
+	//
+	// - - -
+	//
+	// Previous text of this comment:
+	//
+	// > TODO: this is under the assumption that for any depth > 1, if a
+	// > template has already been defined for the given form definition, any
+	// > subsequent nodes matching the repeat's nodeset are implicitly default
+	// > instances. Is this right?
+};
+
+export interface ControlledRepeatDefinition extends RepeatDefinition {
+	readonly count: RepeatCountControlExpression;
+}
+
+export interface UncontrolledRepeatDefinition extends RepeatDefinition {
+	readonly count: null;
+}
+
+/**
+ * Represents a definition of the combined concepts colloquially called a
+ * "repeat", as defined by a form, where those concepts include:
+ *
+ * - A {@link RepeatElementDefinition}—corresponding to a `<repeat>` {@link https://getodk.github.io/xforms-spec/#body-elements | body element}—which is associated with the nodeset referencing the "repeat template" and
+ *   all "repeat instances" (see below points describing both concepts in more detail). The presence of such a body element determines whether to produce a repeat definition (rather than e.g. a {@link SubtreeDefinition}).
+ *
+ * - A "repeat template", defined by a form either
+ *   explicitly,
+ *   or derived from the structure of the first form-defined "repeat instance"
+ *   (as described in the next point).
+ *
+ * - A sequence of one or more model instance nodes, each representing a "repeat instance"
+ *   defined by the form. These nodes contribute to the definition in the following ways:
+ *
+ *   - If an explicit "repeat template" is not defined for
+ *   the "repeat", one is derived from the **structure** (but not the values!)
+ *   of the first such model instance node.
+ *
+ *   - If the "repeat" is {@link ControlledRepeatDefinition | controlled} (i.e. by either a `jr:count` or `jr:noAddRemove` {@link https://getodk.github.io/xforms-spec/#body-attributes | attribute} on the associated {@link RepeatElementDefinition}
+ *
+ * (For construction of this
+ * definition, all other referenced instance nodes are **consumed** in the
+ * process of building the repeat definition's subtree of a
+ * {@link RootDefinition}, ensuring that one repeat definition is produced for
+ * all applicable nodes; they are later referenced for construction of a
+ * form's {@link PrimaryInstance | instance state}.)
+ *
+ * Combined, these concepts produce the details required to instantiate the
+ * {@link RepeatRange} and {@link RepeatInstance} instance state nodes
+ * associated with a defined repeat.
+ */
+export class RepeatDefinition extends DescendentNodeDefinition<'repeat', RepeatElementDefinition> {
+	static from(
+		parent: ParentNodeDefinition,
+		bind: BindDefinition,
+		bodyElement: RepeatElementDefinition,
+		instanceNodes: RepeatInstanceNodes
+	): AnyRepeatDefinition;
+	static from(
+		parent: ParentNodeDefinition,
+		bind: BindDefinition,
+		bodyElement: RepeatElementDefinition,
+		instanceNodes: RepeatInstanceNodes
+	): RepeatDefinition {
+		return new this(parent, bind, bodyElement, instanceNodes);
+	}
+
+	readonly type = 'repeat';
+	readonly children: readonly ChildNodeDefinition[];
+	readonly count: RepeatCountControlExpression | null;
+	readonly template: StaticElement;
+	readonly namespaceDeclarations: NamespaceDeclarationMap;
+	readonly qualifiedName: QualifiedName;
+
+	private constructor(
+		parent: ParentNodeDefinition,
+		bind: BindDefinition,
+		bodyElement: RepeatElementDefinition,
+		instanceNodes: RepeatInstanceNodes
+	) {
+		super(parent, bind, bodyElement);
+
+		const { root } = parent;
+		const [instanceNode] = instanceNodes;
+		const template = parseRepeatTemplateElement(instanceNode);
+		const self = this as AnyRepeatDefinition;
+
+		this.template = template;
+		this.qualifiedName = template.qualifiedName;
+		this.namespaceDeclarations = new NamespaceDeclarationMap(this);
+		this.children = root.buildSubtree(self, template);
+
+		const initialCount = this.omitTemplate(instanceNodes).length;
+
+		this.count = RepeatCountControlExpression.from(bodyElement, initialCount);
+	}
+
+	isControlled(): this is ControlledRepeatDefinition {
+		return this.count != null;
+	}
+
+	isUncontrolled(): this is UncontrolledRepeatDefinition {
+		return this.count == null;
+	}
+
+	omitTemplate(instanceNodes: readonly StaticElement[]): readonly StaticElement[] {
+		return instanceNodes.filter((instanceNode) => {
+			return instanceNode !== this.template;
+		});
+	}
+
+	toJSON(): object {
+		return {};
+	}
+}
+
+// prettier-ignore
+export type AnyRepeatDefinition =
+	| ControlledRepeatDefinition
+	| UncontrolledRepeatDefinition;

package/src/parse/model/RootAttributeDefinition.ts

@@ -5,10 +5,7 @@ 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 qualifiedName: QualifiedName;
 	readonly value: string;
 }
 
@@ -25,16 +22,18 @@ export class RootAttributeDefinition implements NamedNodeDefinition {
 	readonly value: string;
 
 	constructor(root: RootDefinition, source: RootAttributeSource) {
-		const { namespaceURI, nodeName, value } = source;
+		const { qualifiedName, value } = source;
 
 		this.parent = root;
-		this.qualifiedName = new QualifiedName(source);
+		this.qualifiedName = qualifiedName;
 		this.value = value;
 
 		// We serialize namespace declarations separately
-		if (namespaceURI === XMLNS_NAMESPACE_URI) {
+		if (qualifiedName.namespaceURI?.href === XMLNS_NAMESPACE_URI) {
 			this.serializedXML = '';
 		} else {
+			const nodeName = qualifiedName.getPrefixedName();
+
 			this.serializedXML = ` ${nodeName}="${escapeXMLText(value, true)}"`;
 		}
 	}

package/src/parse/model/RootAttributeMap.ts

@@ -1,10 +1,16 @@
 import { XMLNS_NAMESPACE_URI } from '@getodk/common/constants/xmlns.ts';
+import type { StaticAttribute } from '../../integration/xpath/static-dom/StaticAttribute.ts';
+import type { StaticElement } from '../../integration/xpath/static-dom/StaticElement.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 We should probably just distinguish these as separate `StaticNode`
+ * subclasses, probably as separate collections on `StaticElement`!
+ */
+const isNonNamespaceAttribute = (attribute: StaticAttribute) => {
+	return attribute.qualifiedName.namespaceURI?.href !== XMLNS_NAMESPACE_URI;
 };
 
 /**
@@ -24,19 +30,18 @@ const isNonNamespaceDeclarationDOMAttr = (domAttr: Attr) => {
  * @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);
+	static from(root: RootDefinition, instanceNode: StaticElement) {
+		const nonNamespaceAttributes = instanceNode.attributes.filter(isNonNamespaceAttribute);
+		const definitions = nonNamespaceAttributes.map((attribute) => {
+			return new RootAttributeDefinition(root, attribute);
 		});
 
-		return new this(attributes);
+		return new this(definitions);
 	}
 
-	private constructor(attributes: readonly RootAttributeDefinition[]) {
+	private constructor(definitions: readonly RootAttributeDefinition[]) {
 		super(
-			attributes.map((attribute) => {
+			definitions.map((attribute) => {
 				return [attribute.qualifiedName, attribute];
 			})
 		);

package/src/parse/model/RootDefinition.ts

@@ -1,16 +1,17 @@
+import type { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
 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 { FormSubmissionDefinition } from './FormSubmissionDefinition.ts';
 import { LeafNodeDefinition } from './LeafNodeDefinition.ts';
 import type { ModelDefinition } from './ModelDefinition.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 { RepeatDefinition } from './RepeatDefinition.ts';
 import { RootAttributeMap } from './RootAttributeMap.ts';
+import type { SubmissionDefinition } from './SubmissionDefinition.ts';
 import { SubtreeDefinition } from './SubtreeDefinition.ts';
 
 export class RootDefinition extends NodeDefinition<'root'> {
@@ -19,23 +20,21 @@ export class RootDefinition extends NodeDefinition<'root'> {
 	readonly bodyElement = null;
 	readonly root = this;
 	readonly parent = null;
+	readonly template: StaticElement;
 	readonly namespaceDeclarations: NamespaceDeclarationMap;
 	readonly attributes: RootAttributeMap;
 	readonly children: readonly ChildNodeDefinition[];
-	readonly instances = null;
-	readonly node: Element;
-	readonly defaultValue = null;
 
 	readonly isTranslated = false;
 
 	constructor(
 		protected readonly form: XFormDefinition,
 		protected readonly model: ModelDefinition,
-		readonly submission: FormSubmissionDefinition,
+		readonly submission: SubmissionDefinition,
 		readonly classes: BodyClassList
 	) {
-		const { primaryInstanceRoot } = form.xformDOM;
-		const qualifiedName = new QualifiedName(primaryInstanceRoot);
+		const template = model.instance.root;
+		const qualifiedName = template.qualifiedName;
 		const nodeName = qualifiedName.getPrefixedName();
 
 		// TODO: theoretically the pertinent step in the bind's `nodeset` *could* be
@@ -51,23 +50,23 @@ export class RootDefinition extends NodeDefinition<'root'> {
 		super(bind);
 
 		this.qualifiedName = qualifiedName;
-		this.node = primaryInstanceRoot;
-		this.attributes = RootAttributeMap.from(this, primaryInstanceRoot);
+		this.template = template;
+		this.attributes = RootAttributeMap.from(this, template);
 		this.namespaceDeclarations = new NamespaceDeclarationMap(this);
-		this.children = this.buildSubtree(this);
+		this.children = this.buildSubtree(this, template);
 	}
 
-	buildSubtree(parent: ParentNodeDefinition): readonly ChildNodeDefinition[] {
+	buildSubtree(parent: ParentNodeDefinition, node: StaticElement): readonly ChildNodeDefinition[] {
 		const { form, model } = this;
 		const { body } = form;
 		const { binds } = model;
-		const { bind: parentBind, node } = parent;
+		const { bind: parentBind } = parent;
 		const { nodeset: parentNodeset } = parentBind;
 
-		const childrenByName = new Map<string, [Element, ...Element[]]>();
+		const childrenByName = new Map<string, [StaticElement, ...StaticElement[]]>();
 
-		for (const child of node.children) {
-			const { nodeName } = child;
+		for (const child of node.childElements) {
+			const nodeName = child.qualifiedName.getPrefixedName();
 
 			let elements = childrenByName.get(nodeName);
 
@@ -88,7 +87,7 @@ export class RootDefinition extends NodeDefinition<'root'> {
 			const [firstChild, ...restChildren] = children;
 
 			if (bodyElement?.type === 'repeat') {
-				return RepeatRangeDefinition.from(parent, bind, bodyElement, children);
+				return RepeatDefinition.from(parent, bind, bodyElement, children);
 			}
 
 			if (restChildren.length) {
@@ -96,9 +95,8 @@ export class RootDefinition extends NodeDefinition<'root'> {
 			}
 
 			const element = firstChild;
-			const isLeafNode = element.childElementCount === 0;
 
-			if (isLeafNode) {
+			if (element.isLeafElement()) {
 				if (bodyElement?.type === 'range') {
 					return RangeNodeDefinition.from(parent, bind, bodyElement, element);
 				}

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

@@ -1,10 +1,15 @@
 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 type {
+	XFORMS_KNOWN_ATTRIBUTE,
+	XFORMS_LOCAL_NAME,
+	XFormsSecondaryInstanceMap,
+} from '@getodk/xpath';
 import { ErrorProductionDesignPendingError } from '../../../error/ErrorProductionDesignPendingError.ts';
 import type { EngineXPathNode } from '../../../integration/xpath/adapter/kind.ts';
+import type { StaticDocument } from '../../../integration/xpath/static-dom/StaticDocument.ts';
+import type { StaticElement } from '../../../integration/xpath/static-dom/StaticElement.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';
@@ -14,6 +19,22 @@ import { InternalSecondaryInstanceSource } from './sources/InternalSecondaryInst
 import type { SecondaryInstanceSource } from './sources/SecondaryInstanceSource.ts';
 import { XMLExternalSecondaryInstanceSource } from './sources/XMLExternalSecondaryInstanceSource.ts';
 
+export interface SecondaryInstanceDefinition extends StaticDocument {
+	readonly rootDocument: SecondaryInstanceDefinition;
+	readonly root: SecondaryInstanceRootDefinition;
+}
+
+export interface SecondaryInstanceRootDefinition extends StaticElement {
+	readonly [XFORMS_LOCAL_NAME]: 'instance';
+	readonly [XFORMS_KNOWN_ATTRIBUTE]: 'id';
+
+	readonly rootDocument: SecondaryInstanceDefinition;
+	readonly root: SecondaryInstanceRootDefinition;
+
+	getAttributeValue(localName: 'id'): string;
+	getAttributeValue(localName: string): string | null;
+}
+
 export class SecondaryInstancesDefinition
 	extends Map<string, SecondaryInstanceRootDefinition>
 	implements XFormsSecondaryInstanceMap<EngineXPathNode>

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

@@ -0,0 +1,14 @@
+import type { StaticDocument } from '../../../integration/xpath/static-dom/StaticDocument.ts';
+import type { SecondaryInstanceDefinition } from './SecondaryInstancesDefinition.ts';
+
+type AssertSecondaryInstanceDefinition = (
+	doc: StaticDocument
+) => asserts doc is SecondaryInstanceDefinition;
+
+export const assertSecondaryInstanceDefinition: AssertSecondaryInstanceDefinition = ({ root }) => {
+	const id = root.getAttributeValue('id');
+
+	if (id == null) {
+		throw new Error();
+	}
+};

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

@@ -0,0 +1,32 @@
+import { StaticDocument } from '../../../integration/xpath/static-dom/StaticDocument.ts';
+import type { StaticElementOptions } from '../../../integration/xpath/static-dom/StaticElement.ts';
+import { assertSecondaryInstanceDefinition } from './assertSecondaryInstanceDefinition.ts';
+import type { SecondaryInstanceDefinition } from './SecondaryInstancesDefinition.ts';
+
+// prettier-ignore
+type SecondaryInstanceRoot =
+	| StaticElementOptions
+	| '';
+
+export const defineSecondaryInstance = (
+	instanceId: string,
+	secondaryInstanceRoot: SecondaryInstanceRoot
+): SecondaryInstanceDefinition => {
+	const doc = new StaticDocument({
+		documentRoot: {
+			name: 'instance',
+			attributes: [
+				{
+					name: 'id',
+					value: instanceId,
+				},
+			],
+			children: [secondaryInstanceRoot],
+		},
+		nodesetPrefix: `instance('${instanceId}')`,
+	});
+
+	assertSecondaryInstanceDefinition(doc);
+
+	return doc;
+};