@getodk/xforms-engine 0.6.0 → 0.7.0

package/src/parse/model/ModelDefinition.ts

@@ -1,21 +1,54 @@
+import { ErrorProductionDesignPendingError } from '../../error/ErrorProductionDesignPendingError.ts';
+import type { StaticDocument } from '../../integration/xpath/static-dom/StaticDocument.ts';
+import { parseStaticDocumentFromDOMSubtree } from '../shared/parseStaticDocumentFromDOMSubtree.ts';
 import type { XFormDefinition } from '../XFormDefinition.ts';
-import { FormSubmissionDefinition } from './FormSubmissionDefinition.ts';
-import { ItextTranslationsDefinition } from './ItextTranslation/ItextTranslationsDefinition.ts';
+import { ItextTranslationsDefinition } from './ItextTranslationsDefinition.ts';
 import { ModelBindMap } from './ModelBindMap.ts';
+import type { AnyNodeDefinition } from './NodeDefinition.ts';
+import type { NodeDefinitionMap } from './nodeDefinitionMap.ts';
+import { nodeDefinitionMap } from './nodeDefinitionMap.ts';
 import { RootDefinition } from './RootDefinition.ts';
+import { SubmissionDefinition } from './SubmissionDefinition.ts';
 
 export class ModelDefinition {
 	readonly binds: ModelBindMap;
 	readonly root: RootDefinition;
+	readonly nodes: NodeDefinitionMap;
+	readonly instance: StaticDocument;
 	readonly itextTranslations: ItextTranslationsDefinition;
 
 	constructor(readonly form: XFormDefinition) {
-		const submission = new FormSubmissionDefinition(form.xformDOM);
+		const submission = new SubmissionDefinition(form.xformDOM);
+
 		this.binds = ModelBindMap.fromModel(this);
+		this.instance = parseStaticDocumentFromDOMSubtree(form.xformDOM.primaryInstanceRoot, {
+			nodesetPrefix: '/',
+		});
 		this.root = new RootDefinition(form, this, submission, form.body.classes);
+		this.nodes = nodeDefinitionMap(this.root);
 		this.itextTranslations = ItextTranslationsDefinition.from(form.xformDOM);
 	}
 
+	getNodeDefinition(nodeset: string): AnyNodeDefinition {
+		const definition = this.nodes.get(nodeset);
+
+		if (definition == null) {
+			throw new ErrorProductionDesignPendingError(`No definition for nodeset: ${nodeset}`);
+		}
+
+		return definition;
+	}
+
+	getRootDefinition(instance: StaticDocument): RootDefinition {
+		const definition = this.getNodeDefinition(instance.root.nodeset);
+
+		if (definition !== this.root) {
+			throw new ErrorProductionDesignPendingError();
+		}
+
+		return definition;
+	}
+
 	toJSON() {
 		const { form, ...rest } = this;
 

package/src/parse/model/NodeDefinition.ts

@@ -1,3 +1,4 @@
+import type { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
 import type {
 	NamedSubtreeDefinition,
 	NamespaceDeclarationMap,
@@ -7,14 +8,12 @@ import type { AnyBodyElementDefinition } from '../body/BodyDefinition.ts';
 import type { RepeatElementDefinition } from '../body/RepeatElementDefinition.ts';
 import type { BindDefinition } from './BindDefinition.ts';
 import type { LeafNodeDefinition } from './LeafNodeDefinition.ts';
-import type { RepeatInstanceDefinition } from './RepeatInstanceDefinition.ts';
-import type { AnyRepeatRangeDefinition } from './RepeatRangeDefinition.ts';
-import type { RepeatTemplateDefinition } from './RepeatTemplateDefinition.ts';
+import type { AnyRepeatDefinition } from './RepeatDefinition.ts';
 import type { RootDefinition } from './RootDefinition.ts';
 import type { SubtreeDefinition } from './SubtreeDefinition.ts';
 
 /**
- * Corresponds to the model/entry DOM root node, i.e.:
+ * Corresponds to a model instance root node, i.e.:
  *
  * - the element matching `/*` in primary instance expressions, a.k.a.
  * - `/h:html/h:head/xf:model/xf:instance[1]/*`
@@ -22,34 +21,25 @@ import type { SubtreeDefinition } from './SubtreeDefinition.ts';
 export type RootNodeType = 'root';
 
 /**
- * Corresponds to a range/sequence of model/entry DOM subtrees which in turn
- * corresponds to a <repeat> in the form body definition.
- */
-export type RepeatRangeType = 'repeat-range';
-
-/**
- * Corresponds to a template definition for a repeat range, which either has
- * an explicit `jr:template=""` attribute in the form definition or is inferred
- * as a template from the form's first element matched by a <repeat nodeset>.
- */
-export type RepeatTemplateType = 'repeat-template';
-
-/**
- * Corresponds to a single instance of a model/entry DOM subtree which
- * in turn corresponds to a <repeat> in the form body definition, and a
- * 'repeat-range' definition.
+ * Corresponds to the combined concepts defining a "repeat".
+ *
+ * @see {@link RepeatDefinition} for details on these concepts and how they are used to produce a "repeat definition", as such.
+ *
+ * , including or
+ * referencing all of the following:
+ *
  */
-export type RepeatInstanceType = 'repeat-instance';
+export type RepeatType = 'repeat';
 
 /**
- * Corresponds to a model/entry DOM subtree which **does not** correspond to a
+ * Corresponds to a model instance subtree which **does not** correspond to a
  * <repeat> in the form definition. This will typically correspond to a <group>,
  * but this is not strictly necessary per spec (hence the distinct name).
  */
 export type SubtreeNodeType = 'subtree';
 
 /**
- * Corresponds to a model/entry DOM leaf node, i.e. one of:
+ * Corresponds to a model instance leaf node, i.e. one of:
  *
  * - An element with no child elements
  * - Any attribute corresponding to a bind's `nodeset` expression
@@ -60,9 +50,7 @@ export type LeafNodeType = 'leaf-node';
 export type NodeDefinitionType =
 	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
 	| RootNodeType
-	| RepeatRangeType
-	| RepeatTemplateType
-	| RepeatInstanceType
+	| RepeatType
 	| SubtreeNodeType
 	| LeafNodeType;
 
@@ -70,24 +58,15 @@ export type NodeDefinitionType =
 export type ParentNodeDefinition =
 	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
 	| RootDefinition
-	| RepeatTemplateDefinition
-	| RepeatInstanceDefinition
+	| AnyRepeatDefinition
 	| SubtreeDefinition;
 
 // prettier-ignore
 export type ChildNodeDefinition =
-	| AnyRepeatRangeDefinition
+	| AnyRepeatDefinition
 	| LeafNodeDefinition
 	| SubtreeDefinition;
 
-// prettier-ignore
-export type ChildNodeInstanceDefinition =
-	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
-	| RepeatTemplateDefinition
-	| RepeatInstanceDefinition
-	| SubtreeDefinition
-	| LeafNodeDefinition;
-
 export abstract class NodeDefinition<Type extends NodeDefinitionType>
 	implements NamedSubtreeDefinition
 {
@@ -98,12 +77,8 @@ export abstract class NodeDefinition<Type extends NodeDefinitionType>
 	abstract readonly isTranslated: boolean;
 	abstract readonly root: RootDefinition;
 	abstract readonly parent: ParentNodeDefinition | null;
+	abstract readonly template: StaticElement;
 	abstract readonly children: readonly ChildNodeDefinition[] | null;
-	abstract readonly instances: readonly RepeatInstanceDefinition[] | null;
-	abstract readonly defaultValue: string | null;
-
-	/** @todo leaf-node may be Attr */
-	abstract readonly node: Element | null;
 
 	readonly nodeset: string;
 
@@ -112,11 +87,10 @@ export abstract class NodeDefinition<Type extends NodeDefinitionType>
 	}
 }
 
+// prettier-ignore
 export type AnyNodeDefinition =
 	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
 	| RootDefinition
-	| AnyRepeatRangeDefinition
-	| RepeatTemplateDefinition
-	| RepeatInstanceDefinition
+	| AnyRepeatDefinition
 	| SubtreeDefinition
 	| LeafNodeDefinition;

package/src/parse/model/NoteNodeDefinition.ts

@@ -1,5 +1,6 @@
 import type { NoteNode } from '../../client/NoteNode.ts';
 import type { ValueType } from '../../client/ValueType.ts';
+import type { StaticLeafElement } from '../../integration/xpath/static-dom/StaticElement.ts';
 import type { AnyBodyElementDefinition } from '../body/BodyDefinition.ts';
 import type { InputControlDefinition } from '../body/control/InputControlDefinition.ts';
 import { BindComputationExpression } from '../expression/BindComputationExpression.ts';
@@ -43,7 +44,7 @@ export class NoteNodeDefinition<V extends ValueType = ValueType> extends LeafNod
 		parent: ParentNodeDefinition,
 		bind: BindDefinition<V>,
 		bodyElement: AnyBodyElementDefinition | null,
-		node: Element
+		node: StaticLeafElement
 	): NoteNodeDefinition<V> | null {
 		if (!isNoteBindDefinition(bind) || bodyElement?.type !== 'input') {
 			return null;
@@ -64,8 +65,8 @@ export class NoteNodeDefinition<V extends ValueType = ValueType> extends LeafNod
 		override readonly bind: NoteBindDefinition<V>,
 		override readonly bodyElement: InputControlDefinition,
 		readonly noteTextDefinition: NoteTextDefinition,
-		node: Element
+		template: StaticLeafElement
 	) {
-		super(parent, bind, bodyElement, node);
+		super(parent, bind, bodyElement, template);
 	}
 }

package/src/parse/model/RangeNodeDefinition.ts

@@ -1,5 +1,6 @@
 import type { ValueType } from '../../client/ValueType.ts';
 import { ErrorProductionDesignPendingError } from '../../error/ErrorProductionDesignPendingError.ts';
+import type { StaticLeafElement } from '../../integration/xpath/static-dom/StaticElement.ts';
 import type { RuntimeValue, SharedValueCodec } from '../../lib/codecs/getSharedValueCodec.ts';
 import { getSharedValueCodec } from '../../lib/codecs/getSharedValueCodec.ts';
 import type {
@@ -91,7 +92,7 @@ export class RangeNodeDefinition<V extends RangeValueType = RangeValueType>
 		parent: ParentNodeDefinition,
 		bind: BindDefinition<V>,
 		bodyElement: RangeControlDefinition,
-		node: Element
+		node: StaticLeafElement
 	): RangeNodeDefinition<Extract<V, RangeValueType>> {
 		assertRangeBindDefinition(bind);
 
@@ -104,7 +105,7 @@ export class RangeNodeDefinition<V extends RangeValueType = RangeValueType>
 		parent: ParentNodeDefinition,
 		override readonly bind: BindDefinition<V>,
 		override readonly bodyElement: RangeControlDefinition,
-		node: Element
+		node: StaticLeafElement
 	) {
 		super(parent, bind, bodyElement, node);
 

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)}"`;
 		}
 	}