@getodk/xforms-engine 0.1.1 → 0.3.0

package/src/model/NodeDefinition.ts

@@ -1,12 +1,12 @@
 import type { AnyBodyElementDefinition } from '../body/BodyDefinition.ts';
-import type { RepeatDefinition } from '../body/RepeatDefinition.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 { RepeatSequenceDefinition } from './RepeatSequenceDefinition.ts';
+import type { AnyRepeatRangeDefinition } from './RepeatRangeDefinition.ts';
 import type { RepeatTemplateDefinition } from './RepeatTemplateDefinition.ts';
 import type { RootDefinition } from './RootDefinition.ts';
 import type { SubtreeDefinition } from './SubtreeDefinition.ts';
-import type { ValueNodeDefinition } from './ValueNodeDefinition.ts';
 
 /**
  * Corresponds to the model/entry DOM root node, i.e.:
@@ -17,13 +17,13 @@ import type { ValueNodeDefinition } from './ValueNodeDefinition.ts';
 export type RootNodeType = 'root';
 
 /**
- * Corresponds to a sequence of model/entry DOM subtrees which in turn
+ * Corresponds to a range/sequence of model/entry DOM subtrees which in turn
  * corresponds to a <repeat> in the form body definition.
  */
-export type RepeatSequenceType = 'repeat-sequence';
+export type RepeatRangeType = 'repeat-range';
 
 /**
- * Corresponds to a template definition for a repeat sequence, which either has
+ * 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>.
  */
@@ -32,7 +32,7 @@ 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-sequence' definition.
+ * 'repeat-range' definition.
  */
 export type RepeatInstanceType = 'repeat-instance';
 
@@ -49,17 +49,17 @@ export type SubtreeNodeType = 'subtree';
  * - An element with no child elements
  * - Any attribute corresponding to a bind's `nodeset` expression
  */
-export type ValueNodeType = 'value-node';
+export type LeafNodeType = 'leaf-node';
 
 // prettier-ignore
 export type NodeDefinitionType =
 	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
 	| RootNodeType
-	| RepeatSequenceType
+	| RepeatRangeType
 	| RepeatTemplateType
 	| RepeatInstanceType
 	| SubtreeNodeType
-	| ValueNodeType;
+	| LeafNodeType;
 
 // prettier-ignore
 export type ParentNodeDefinition =
@@ -71,9 +71,9 @@ export type ParentNodeDefinition =
 
 // prettier-ignore
 export type ChildNodeDefinition =
-	| RepeatSequenceDefinition
-	| SubtreeDefinition
-	| ValueNodeDefinition;
+	| AnyRepeatRangeDefinition
+	| LeafNodeDefinition
+	| SubtreeDefinition;
 
 // prettier-ignore
 export type ChildNodeInstanceDefinition =
@@ -81,7 +81,7 @@ export type ChildNodeInstanceDefinition =
 	| RepeatTemplateDefinition
 	| RepeatInstanceDefinition
 	| SubtreeDefinition
-	| ValueNodeDefinition;
+	| LeafNodeDefinition;
 
 // prettier-ignore
 export type NodeChildren<Type extends NodeDefinitionType> =
@@ -91,7 +91,7 @@ export type NodeChildren<Type extends NodeDefinitionType> =
 
 // prettier-ignore
 export type NodeInstances<Type extends NodeDefinitionType> =
-	Type extends 'repeat-sequence'
+	Type extends 'repeat-range'
 		? readonly RepeatInstanceDefinition[]
 		: null;
 
@@ -101,16 +101,16 @@ export type NodeParent<Type extends NodeDefinitionType> =
 		? ParentNodeDefinition
 		: null;
 
-// TODO: value-node may be Attr
+// TODO: leaf-node may be Attr
 // prettier-ignore
 export type ModelNode<Type extends NodeDefinitionType> =
-	Type extends 'repeat-sequence'
+	Type extends 'repeat-range'
 		? null
 		: Element;
 
 // prettier-ignore
 export type NodeDefaultValue<Type extends NodeDefinitionType> =
-	Type extends 'value-node'
+	Type extends 'leaf-node'
 		? string
 		: null;
 
@@ -120,7 +120,7 @@ export interface NodeDefinition<Type extends NodeDefinitionType> {
 	readonly bind: BindDefinition;
 	readonly nodeset: string;
 	readonly nodeName: string;
-	readonly bodyElement: AnyBodyElementDefinition | RepeatDefinition | null;
+	readonly bodyElement: AnyBodyElementDefinition | RepeatElementDefinition | null;
 
 	readonly isTranslated: boolean;
 	readonly dependencyExpressions: ReadonlySet<string>;
@@ -137,10 +137,10 @@ export interface NodeDefinition<Type extends NodeDefinitionType> {
 export type AnyNodeDefinition =
 	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
 	| RootDefinition
-	| RepeatSequenceDefinition
+	| AnyRepeatRangeDefinition
 	| RepeatTemplateDefinition
 	| RepeatInstanceDefinition
 	| SubtreeDefinition
-	| ValueNodeDefinition;
+	| LeafNodeDefinition;
 
 export type TypedNodeDefinition<Type> = Extract<AnyNodeDefinition, { readonly type: Type }>;

package/src/model/RepeatInstanceDefinition.ts

@@ -1,10 +1,10 @@
-import { RepeatDefinition } from '../body/RepeatDefinition.ts';
+import { RepeatElementDefinition } from '../body/RepeatElementDefinition.ts';
 import { DescendentNodeDefinition } from './DescendentNodeDefinition.ts';
 import type { ChildNodeDefinition, NodeDefinition } from './NodeDefinition.ts';
-import type { RepeatSequenceDefinition } from './RepeatSequenceDefinition.ts';
+import type { AnyRepeatRangeDefinition } from './RepeatRangeDefinition.ts';
 
 export class RepeatInstanceDefinition
-	extends DescendentNodeDefinition<'repeat-instance', RepeatDefinition>
+	extends DescendentNodeDefinition<'repeat-instance', RepeatElementDefinition>
 	implements NodeDefinition<'repeat-instance'>
 {
 	readonly type = 'repeat-instance';
@@ -15,24 +15,19 @@ export class RepeatInstanceDefinition
 	readonly defaultValue = null;
 
 	constructor(
-		protected readonly sequence: RepeatSequenceDefinition,
+		range: AnyRepeatRangeDefinition,
 		readonly node: Element
 	) {
-		const {
-			bind,
-			bodyElement: repeatGroupBodyElement,
-			parent: repeatSequenceParent,
-			root,
-		} = sequence;
+		const { bind, bodyElement, parent, root } = range;
 
-		super(repeatSequenceParent, bind, repeatGroupBodyElement.repeat);
+		super(parent, bind, bodyElement);
 
-		this.nodeName = sequence.nodeName;
+		this.nodeName = range.nodeName;
 		this.children = root.buildSubtree(this);
 	}
 
 	toJSON() {
-		const { bind, bodyElement, parent, root, sequence, ...rest } = this;
+		const { bind, bodyElement, parent, root, ...rest } = this;
 
 		return rest;
 	}

package/src/model/RepeatRangeDefinition.ts

@@ -0,0 +1,94 @@
+import type { RepeatElementDefinition } from '../body/RepeatElementDefinition.ts';
+import { RepeatCountControlExpression } from '../parse/expression/RepeatCountControlExpression.ts';
+import type { BindDefinition } from './BindDefinition.ts';
+import { DescendentNodeDefinition } from './DescendentNodeDefinition.ts';
+import type { NodeDefinition, ParentNodeDefinition } from './NodeDefinition.ts';
+import { RepeatInstanceDefinition } from './RepeatInstanceDefinition.ts';
+import { RepeatTemplateDefinition } from './RepeatTemplateDefinition.ts';
+
+export interface ControlledRepeatRangeDefinition extends RepeatRangeDefinition {
+	readonly count: RepeatCountControlExpression;
+}
+
+export interface UncontrolledRepeatRangeDefinition extends RepeatRangeDefinition {
+	readonly count: null;
+}
+
+// prettier-ignore
+export type AnyRepeatRangeDefinition =
+	| ControlledRepeatRangeDefinition
+	| UncontrolledRepeatRangeDefinition;
+
+type AssertRepeatRangeDefinitionUnion = (
+	definition: RepeatRangeDefinition
+) => asserts definition is AnyRepeatRangeDefinition;
+
+const assertRepeatRangeDefinitionUnion: AssertRepeatRangeDefinitionUnion = (_definition) => {
+	// Intentional no-op, used to guide the type checker. Implementation would
+	// check _definition.count == null || _definition.count != null, which is
+	// tautologically true!
+};
+
+export class RepeatRangeDefinition
+	extends DescendentNodeDefinition<'repeat-range', RepeatElementDefinition>
+	implements NodeDefinition<'repeat-range'>
+{
+	static from(
+		parent: ParentNodeDefinition,
+		bind: BindDefinition,
+		bodyElement: RepeatElementDefinition,
+		modelNodes: readonly [Element, ...Element[]]
+	): AnyRepeatRangeDefinition {
+		const definition = new this(parent, bind, bodyElement, modelNodes);
+
+		assertRepeatRangeDefinitionUnion(definition);
+
+		return definition;
+	}
+
+	readonly type = 'repeat-range';
+
+	readonly template: RepeatTemplateDefinition;
+	readonly children = null;
+	readonly instances: RepeatInstanceDefinition[];
+	readonly count: RepeatCountControlExpression | null;
+
+	readonly node = null;
+	readonly nodeName: string;
+	readonly defaultValue = null;
+
+	private constructor(
+		parent: ParentNodeDefinition,
+		bind: BindDefinition,
+		bodyElement: RepeatElementDefinition,
+		modelNodes: readonly [Element, ...Element[]]
+	) {
+		super(parent, bind, bodyElement);
+
+		const { template, instanceNodes } = RepeatTemplateDefinition.parseModelNodes(this, modelNodes);
+
+		this.template = template;
+		this.nodeName = template.nodeName;
+		this.count = RepeatCountControlExpression.from(bodyElement, instanceNodes.length);
+
+		assertRepeatRangeDefinitionUnion(this);
+
+		this.instances = instanceNodes.map((element) => {
+			return new RepeatInstanceDefinition(this, element);
+		});
+	}
+
+	isControlled(): this is ControlledRepeatRangeDefinition {
+		return this.count != null;
+	}
+
+	isUncontrolled(): this is UncontrolledRepeatRangeDefinition {
+		return this.count == null;
+	}
+
+	toJSON() {
+		const { bind, bodyElement: groupDefinition, parent, root, ...rest } = this;
+
+		return rest;
+	}
+}

package/src/model/RepeatTemplateDefinition.ts

@@ -1,9 +1,9 @@
 import { JAVAROSA_NAMESPACE_URI } from '@getodk/common/constants/xmlns.ts';
-import type { RepeatDefinition } from '../body/RepeatDefinition.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 { RepeatSequenceDefinition } from './RepeatSequenceDefinition.ts';
+import type { RepeatRangeDefinition } from './RepeatRangeDefinition.ts';
 
 const repeatTemplates = new WeakMap<BindDefinition, RepeatTemplateDefinition>();
 
@@ -73,14 +73,14 @@ interface ParsedRepeatNodes {
 }
 
 export class RepeatTemplateDefinition
-	extends DescendentNodeDefinition<'repeat-template', RepeatDefinition>
+	extends DescendentNodeDefinition<'repeat-template', RepeatElementDefinition>
 	implements NodeDefinition<'repeat-template'>
 {
 	static parseModelNodes(
-		sequence: RepeatSequenceDefinition,
+		range: RepeatRangeDefinition,
 		modelNodes: readonly [Element, ...Element[]]
 	): ParsedRepeatNodes {
-		const { bind } = sequence;
+		const { bind } = range;
 
 		let template = repeatTemplates.get(bind);
 		let instanceNodes: readonly Element[];
@@ -89,7 +89,7 @@ export class RepeatTemplateDefinition
 			const [templateNode, ...rest] = splitInstanceNodes(modelNodes);
 
 			instanceNodes = rest;
-			template = new this(sequence, templateNode);
+			template = new this(range, templateNode);
 		} else {
 			// TODO: this is under the assumption that for any depth > 1, if a
 			// template has already been defined for the given form definition, any
@@ -121,17 +121,12 @@ export class RepeatTemplateDefinition
 	readonly defaultValue = null;
 
 	protected constructor(
-		protected readonly sequence: RepeatSequenceDefinition,
+		range: RepeatRangeDefinition,
 		protected readonly templateNode: ExplicitRepeatTemplateElement
 	) {
-		const {
-			bind,
-			bodyElement: repeatGroupBodyElement,
-			parent: repeatSequenceParent,
-			root,
-		} = sequence;
+		const { bind, bodyElement, parent, root } = range;
 
-		super(repeatSequenceParent, bind, repeatGroupBodyElement.repeat);
+		super(parent, bind, bodyElement);
 
 		const node = templateNode.cloneNode(true) as Element;
 
@@ -143,7 +138,7 @@ export class RepeatTemplateDefinition
 	}
 
 	toJSON() {
-		const { bind, bodyElement, parent, root, sequence, ...rest } = this;
+		const { bind, bodyElement, parent, root, ...rest } = this;
 
 		return rest;
 	}

package/src/model/RootDefinition.ts

@@ -1,15 +1,16 @@
 import type { XFormDefinition } from '../XFormDefinition.ts';
-import type { RepeatGroupDefinition } from '../body/group/RepeatGroupDefinition.ts';
+import type { BodyClassList } from '../body/BodyDefinition.ts';
+import { NoteNodeDefinition } from '../parse/NoteNodeDefinition.ts';
 import type { BindDefinition } from './BindDefinition.ts';
+import { LeafNodeDefinition } from './LeafNodeDefinition.ts';
 import type { ModelDefinition } from './ModelDefinition.ts';
 import type {
 	ChildNodeDefinition,
 	NodeDefinition,
 	ParentNodeDefinition,
 } from './NodeDefinition.ts';
-import { RepeatSequenceDefinition } from './RepeatSequenceDefinition.ts';
+import { RepeatRangeDefinition } from './RepeatRangeDefinition.ts';
 import { SubtreeDefinition } from './SubtreeDefinition.ts';
-import { ValueNodeDefinition } from './ValueNodeDefinition.ts';
 
 export class RootDefinition implements NodeDefinition<'root'> {
 	readonly type = 'root';
@@ -29,7 +30,8 @@ export class RootDefinition implements NodeDefinition<'root'> {
 
 	constructor(
 		protected readonly form: XFormDefinition,
-		protected readonly model: ModelDefinition
+		protected readonly model: ModelDefinition,
+		readonly classes: BodyClassList
 	) {
 		// TODO: theoretically the pertinent step in the bind's `nodeset` *could* be
 		// namespaced. It also may make more sense to determine the root nodeset
@@ -86,16 +88,9 @@ export class RootDefinition implements NodeDefinition<'root'> {
 			const bind = binds.getOrCreateBindDefinition(nodeset);
 			const bodyElement = body.getBodyElement(nodeset);
 			const [firstChild, ...restChildren] = children;
-			const repeatGroup = body.getRepeatGroup(nodeset);
 
-			if (repeatGroup != null) {
-				const repeatDefinition = (bodyElement as RepeatGroupDefinition).repeat;
-
-				if (repeatDefinition == null) {
-					throw 'TODO: this is why I have hesitated to pick an "is repeat" predicate direction';
-				}
-
-				return new RepeatSequenceDefinition(parent, bind, repeatGroup, children);
+			if (bodyElement?.type === 'repeat') {
+				return RepeatRangeDefinition.from(parent, bind, bodyElement, children);
 			}
 
 			if (restChildren.length) {
@@ -106,7 +101,10 @@ export class RootDefinition implements NodeDefinition<'root'> {
 			const isLeafNode = element.childElementCount === 0;
 
 			if (isLeafNode) {
-				return new ValueNodeDefinition(parent, bind, bodyElement, element);
+				return (
+					NoteNodeDefinition.from(parent, bind, bodyElement, element) ??
+					new LeafNodeDefinition(parent, bind, bodyElement, element)
+				);
 			}
 
 			return new SubtreeDefinition(parent, bind, bodyElement, element);

package/src/model/SubtreeDefinition.ts

@@ -1,6 +1,6 @@
 import type {
 	AnyBodyElementDefinition,
-	NonRepeatGroupElementDefinition,
+	AnyGroupElementDefinition,
 } from '../body/BodyDefinition.ts';
 import type { BindDefinition } from './BindDefinition.ts';
 import { DescendentNodeDefinition } from './DescendentNodeDefinition.ts';
@@ -11,7 +11,7 @@ import type {
 } from './NodeDefinition.ts';
 
 export class SubtreeDefinition
-	extends DescendentNodeDefinition<'subtree', NonRepeatGroupElementDefinition | null>
+	extends DescendentNodeDefinition<'subtree', AnyGroupElementDefinition | null>
 	implements NodeDefinition<'subtree'>
 {
 	readonly type = 'subtree';
@@ -29,7 +29,7 @@ export class SubtreeDefinition
 	) {
 		if (
 			bodyElement != null &&
-			(bodyElement.category !== 'structure' || bodyElement.type === 'repeat-group')
+			(bodyElement.category !== 'structure' || bodyElement.type === 'repeat')
 		) {
 			throw new Error(`Unexpected body element for nodeset ${bind.nodeset}`);
 		}

package/src/parse/NoteNodeDefinition.ts

@@ -0,0 +1,70 @@
+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';
+
+// prettier-ignore
+export type NoteReadonlyDefinition =
+	&	BindComputation<'readonly'>
+	& ConstantTruthyDependentExpression;
+
+export interface NoteBindDefinition extends BindDefinition {
+	readonly readonly: NoteReadonlyDefinition;
+}
+
+const isNoteBindDefinition = (bind: BindDefinition): bind is NoteBindDefinition => {
+	return bind.readonly.isConstantTruthyExpression();
+};
+
+// prettier-ignore
+export type NoteTextDefinition =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| LabelDefinition
+	| HintDefinition;
+
+/**
+ * @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
+ * 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
+ * distinct {@link NoteNode.currentState} types) to handle note-specific logic.
+ */
+export class NoteNodeDefinition extends LeafNodeDefinition {
+	static from(
+		parent: ParentNodeDefinition,
+		bind: BindDefinition,
+		bodyElement: AnyBodyElementDefinition | null,
+		node: Element
+	): NoteNodeDefinition | null {
+		if (!isNoteBindDefinition(bind) || bodyElement?.type !== 'input') {
+			return null;
+		}
+
+		const { label, hint } = bodyElement;
+		const noteTextDefinition = label ?? hint;
+
+		if (noteTextDefinition == null) {
+			return null;
+		}
+
+		return new this(parent, bind, bodyElement, noteTextDefinition, node);
+	}
+
+	constructor(
+		parent: ParentNodeDefinition,
+		override readonly bind: NoteBindDefinition,
+		override readonly bodyElement: InputDefinition,
+		readonly noteTextDefinition: NoteTextDefinition,
+		node: Element
+	) {
+		super(parent, bind, bodyElement, node);
+	}
+}

package/src/parse/TODO.md

@@ -0,0 +1,3 @@
+# @getodk/xforms-engine: parse
+
+Presence of this file is intended to be temporary! It is here to signal the intent to make a clearer distinction between the parsing and runtime aspects of the engine implementation. For entirely pragmatic purposes, newly introduced will be added here to start. We can decide in review if we want to move the rest into this directory right away. (For existing/untouched code, this would just mean moving the files and updating imports to reflect that. Small effort, lots of potential diff noise.)

package/src/parse/expression/RepeatCountControlExpression.ts

@@ -0,0 +1,44 @@
+import { RepeatElementDefinition } from '../../body/RepeatElementDefinition.ts';
+import type { RepeatRangeControlledNode } from '../../client/repeat/RepeatRangeControlledNode.ts';
+import { DependentExpression } from '../../expression/DependentExpression.ts';
+import { isConstantTruthyExpression } from '../xpath/semantic-analysis.ts';
+
+/**
+ * Represents either of these
+ * {@link https://getodk.github.io/xforms-spec/#body-attributes | body attributes}:
+ *
+ * - `jr:count`
+ * - `jr:noAddRemove`
+ *
+ * In both cases, the downstream effect is that the engine is responsible for
+ * controlling the count of a repeat range's instances. Representing both cases
+ * should simplify client usage, as well as implementation of the internal
+ * representation of {@link RepeatRangeControlledNode}.
+ */
+export class RepeatCountControlExpression extends DependentExpression<'number'> {
+	static from(
+		bodyElement: RepeatElementDefinition,
+		initialCount: number
+	): RepeatCountControlExpression | null {
+		const { countExpression, noAddRemoveExpression } = bodyElement;
+
+		if (countExpression != null) {
+			return new this(bodyElement, countExpression);
+		}
+
+		if (noAddRemoveExpression != null && isConstantTruthyExpression(noAddRemoveExpression)) {
+			// Assumption: `noAddRemove` with no form-defined repeat instances has no
+			// purpose. Infer intent as a single repeat instance, as defined by the
+			// repeat's template.
+			const fixedCountExpression = String(Math.max(initialCount, 1));
+
+			return new this(bodyElement, fixedCountExpression);
+		}
+
+		return null;
+	}
+
+	private constructor(context: RepeatElementDefinition, expression: string) {
+		super(context, 'number', expression);
+	}
+}

package/src/parse/text/HintDefinition.ts

@@ -0,0 +1,25 @@
+import type { LocalNamedElement } from '@getodk/common/types/dom.ts';
+import type { XFormDefinition } from '../../XFormDefinition.ts';
+import type { AnyControlDefinition } from '../../body/control/ControlDefinition.ts';
+import { getHintElement } from '../../lib/dom/query.ts';
+import { TextElementDefinition } from './abstract/TextElementDefinition.ts';
+
+interface HintElement extends LocalNamedElement<'hint'> {}
+
+export class HintDefinition extends TextElementDefinition<'hint'> {
+	static forElement(form: XFormDefinition, owner: AnyControlDefinition): HintDefinition | null {
+		const hintElement = getHintElement(owner.element);
+
+		if (hintElement == null) {
+			return null;
+		}
+
+		return new this(form, owner, hintElement);
+	}
+
+	readonly role = 'hint';
+
+	private constructor(form: XFormDefinition, owner: AnyControlDefinition, element: HintElement) {
+		super(form, owner, element);
+	}
+}

package/src/parse/text/ItemLabelDefinition.ts

@@ -0,0 +1,25 @@
+import type { LocalNamedElement } from '@getodk/common/types/dom.ts';
+import type { XFormDefinition } from '../../XFormDefinition.ts';
+import type { ItemDefinition } from '../../body/control/select/ItemDefinition.ts';
+import { getLabelElement } from '../../lib/dom/query.ts';
+import { TextElementDefinition } from './abstract/TextElementDefinition.ts';
+
+interface LabelElement extends LocalNamedElement<'label'> {}
+
+export class ItemLabelDefinition extends TextElementDefinition<'item-label'> {
+	static from(form: XFormDefinition, owner: ItemDefinition): ItemLabelDefinition | null {
+		const labelElement = getLabelElement(owner.element);
+
+		if (labelElement == null) {
+			return null;
+		}
+
+		return new this(form, owner, labelElement);
+	}
+
+	readonly role = 'item-label';
+
+	private constructor(form: XFormDefinition, owner: ItemDefinition, element: LabelElement) {
+		super(form, owner, element);
+	}
+}

package/src/parse/text/ItemsetLabelDefinition.ts

@@ -0,0 +1,44 @@
+import type { LocalNamedElement } from '@getodk/common/types/dom.ts';
+import type { XFormDefinition } from '../../XFormDefinition.ts';
+import type { ItemDefinition } from '../../body/control/select/ItemDefinition.ts';
+import type { ItemsetDefinition } from '../../body/control/select/ItemsetDefinition.ts';
+import { getLabelElement } from '../../lib/dom/query.ts';
+import { ReferenceChunkDefinition } from './ReferenceChunkDefinition.ts';
+import { TranslationChunkDefinition } from './TranslationChunkDefinition.ts';
+import type { RefAttributeChunk } from './abstract/TextElementDefinition.ts';
+import { TextRangeDefinition } from './abstract/TextRangeDefinition.ts';
+
+export type ItemLabelOwner = ItemDefinition | ItemsetDefinition;
+
+interface LabelElement extends LocalNamedElement<'label'> {}
+
+export class ItemsetLabelDefinition extends TextRangeDefinition<'item-label'> {
+	static from(form: XFormDefinition, owner: ItemsetDefinition): ItemsetLabelDefinition | null {
+		const labelElement = getLabelElement(owner.element);
+
+		if (labelElement == null) {
+			return null;
+		}
+
+		return new this(form, owner, labelElement);
+	}
+
+	readonly role = 'item-label';
+	readonly chunks: readonly [RefAttributeChunk];
+
+	private constructor(form: XFormDefinition, owner: ItemsetDefinition, element: LabelElement) {
+		super(form, owner, element);
+
+		const refExpression = element.getAttribute('ref');
+
+		if (refExpression == null) {
+			throw new Error('<itemset><label> missing ref attribute');
+		}
+
+		const refChunk =
+			TranslationChunkDefinition.from(this, refExpression) ??
+			ReferenceChunkDefinition.from(this, refExpression);
+
+		this.chunks = [refChunk];
+	}
+}