@getodk/xforms-engine 0.2.0 → 0.4.0

package/src/instance/internal-api/ValidationContext.ts

@@ -0,0 +1,32 @@
+import type { AnyViolation } from '../../client/validation.ts';
+import type { BindComputationExpression } from '../../parse/expression/BindComputationExpression.ts';
+import type { MessageDefinition } from '../../parse/text/MessageDefinition.ts';
+import type { NodeID } from '../identity.ts';
+import type { EvaluationContext } from './EvaluationContext.ts';
+import type { SubscribableDependency } from './SubscribableDependency.ts';
+
+interface ValidationContextCurrentState {
+	get reference(): string;
+}
+
+interface ValidationContextDefinitionBind {
+	readonly constraint: BindComputationExpression<'constraint'>;
+	readonly constraintMsg: MessageDefinition<'constraintMsg'> | null;
+	readonly required: BindComputationExpression<'required'>;
+	readonly requiredMsg: MessageDefinition<'requiredMsg'> | null;
+}
+
+interface ValidationContextDefinition {
+	readonly bind: ValidationContextDefinitionBind;
+}
+
+export interface ValidationContext extends EvaluationContext, SubscribableDependency {
+	readonly nodeId: NodeID;
+	readonly definition: ValidationContextDefinition;
+	readonly currentState: ValidationContextCurrentState;
+
+	getViolation(): AnyViolation | null;
+	isRelevant(): boolean;
+	isRequired(): boolean;
+	isBlank(): boolean;
+}

package/src/instance/internal-api/ValueContext.ts

@@ -1,12 +1,12 @@
 import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
-import type { BindComputation } from '../../model/BindComputation.ts';
+import type { BindComputationExpression } from '../../parse/expression/BindComputationExpression.ts';
 import type { EvaluationContext } from './EvaluationContext.ts';
 
 export type InstanceValue = string;
 
 interface ValueContextDefinitionBind {
-	readonly calculate: BindComputation<'calculate'> | null;
-	readonly readonly: BindComputation<'readonly'>;
+	readonly calculate: BindComputationExpression<'calculate'> | null;
+	readonly readonly: BindComputationExpression<'readonly'>;
 }
 
 export interface ValueContextDefinition {

package/src/instance/{RepeatRange.ts → repeat/BaseRepeatRange.ts}

@@ -1,27 +1,34 @@
 import { insertAtIndex } from '@getodk/common/lib/array/insert.ts';
-import type { Accessor } from 'solid-js';
-import type { RepeatRangeNode, RepeatRangeNodeAppearances } from '../client/RepeatRangeNode.ts';
-import type { ChildrenState } from '../lib/reactivity/createChildrenState.ts';
-import { createChildrenState } from '../lib/reactivity/createChildrenState.ts';
-import { createComputedExpression } from '../lib/reactivity/createComputedExpression.ts';
-import type { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
-import { materializeCurrentStateChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
-import type { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
-import type { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
-import type { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
-import { createSharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
-import { createNodeLabel } from '../lib/reactivity/text/createNodeLabel.ts';
-import type { RepeatRangeDefinition } from '../model/RepeatRangeDefinition.ts';
-import type { RepeatDefinition } from './RepeatInstance.ts';
-import { RepeatInstance } from './RepeatInstance.ts';
-import type { Root } from './Root.ts';
-import type { DescendantNodeSharedStateSpec } from './abstract/DescendantNode.ts';
-import { DescendantNode } from './abstract/DescendantNode.ts';
-import type { GeneralParentNode } from './hierarchy.ts';
-import type { NodeID } from './identity.ts';
-import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
-import type { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
-import type { TextRange } from './text/TextRange.ts';
+import { untrack, type Accessor } from 'solid-js';
+import type { NodeAppearances } from '../../client/NodeAppearances.ts';
+import type { BaseRepeatRangeNode } from '../../client/repeat/BaseRepeatRangeNode.ts';
+import type { TextRange } from '../../client/TextRange.ts';
+import type { AncestorNodeValidationState } from '../../client/validation.ts';
+import type { ChildrenState } from '../../lib/reactivity/createChildrenState.ts';
+import { createChildrenState } from '../../lib/reactivity/createChildrenState.ts';
+import { createComputedExpression } from '../../lib/reactivity/createComputedExpression.ts';
+import type { MaterializedChildren } from '../../lib/reactivity/materializeCurrentStateChildren.ts';
+import { materializeCurrentStateChildren } from '../../lib/reactivity/materializeCurrentStateChildren.ts';
+import type { CurrentState } from '../../lib/reactivity/node-state/createCurrentState.ts';
+import type { EngineState } from '../../lib/reactivity/node-state/createEngineState.ts';
+import type { SharedNodeState } from '../../lib/reactivity/node-state/createSharedNodeState.ts';
+import { createSharedNodeState } from '../../lib/reactivity/node-state/createSharedNodeState.ts';
+import { createNodeLabel } from '../../lib/reactivity/text/createNodeLabel.ts';
+import type {
+	AnyRepeatRangeDefinition,
+	ControlledRepeatRangeDefinition,
+} from '../../parse/model/RepeatRangeDefinition.ts';
+import type {
+	AnyDescendantNode,
+	DescendantNodeParent,
+	DescendantNodeSharedStateSpec,
+} from '../abstract/DescendantNode.ts';
+import { DescendantNode } from '../abstract/DescendantNode.ts';
+import type { RepeatRange } from '../hierarchy.ts';
+import type { NodeID } from '../identity.ts';
+import type { EvaluationContext } from '../internal-api/EvaluationContext.ts';
+import type { SubscribableDependency } from '../internal-api/SubscribableDependency.ts';
+import { RepeatInstance, type RepeatDefinition } from './RepeatInstance.ts';
 
 interface RepeatRangeStateSpec extends DescendantNodeSharedStateSpec {
 	readonly hint: null;
@@ -31,9 +38,15 @@ interface RepeatRangeStateSpec extends DescendantNodeSharedStateSpec {
 	readonly value: null;
 }
 
-export class RepeatRange
-	extends DescendantNode<RepeatRangeDefinition, RepeatRangeStateSpec, RepeatInstance>
-	implements RepeatRangeNode, EvaluationContext, SubscribableDependency
+// prettier-ignore
+type BaseRepeatRangeNodeType<Definition extends AnyRepeatRangeDefinition> =
+	Definition extends ControlledRepeatRangeDefinition
+		? 'repeat-range:controlled'
+		: 'repeat-range:uncontrolled';
+
+export abstract class BaseRepeatRange<Definition extends AnyRepeatRangeDefinition>
+	extends DescendantNode<Definition, RepeatRangeStateSpec, RepeatInstance>
+	implements BaseRepeatRangeNode, EvaluationContext, SubscribableDependency
 {
 	/**
 	 * A repeat range doesn't have a corresponding primary instance element of its
@@ -57,14 +70,36 @@ export class RepeatRange
 	 * {@link https://developer.mozilla.org/en-US/docs/Web/API/Range | DOM Range}
 	 * instead?
 	 */
-	private readonly anchorNode: Comment;
+	protected readonly anchorNode: Comment;
+
+	protected readonly childrenState: ChildrenState<RepeatInstance>;
+
+	/**
+	 * Provides an {@link EvaluationContext} from which to evaluate expressions
+	 * where some LocationPath sub-expressions may be **relative to the repeat
+	 * range itself**. This is useful for evaluation of expressions where:
+	 *
+	 * - the expression is typically contextualized to any of its
+	 *   {@link RepeatInstance} children, but it presently has none (i.e.
+	 *   `relevant`)
+	 *
+	 * - the expression is conceptually intended to be evaluated in the context of
+	 *   the repeat range itself (i.e. `jr:count`)
+	 */
+	protected readonly selfEvaluationContext: EvaluationContext & {
+		readonly contextNode: Comment;
+	};
 
-	private readonly childrenState: ChildrenState<RepeatInstance>;
+	/**
+	 * @see {@link isSelfRelevant}
+	 */
+	protected readonly isEmptyRangeSelfRelevant: Accessor<boolean>;
 
 	// InstanceNode
 	protected readonly state: SharedNodeState<RepeatRangeStateSpec>;
 	protected override engineState: EngineState<RepeatRangeStateSpec>;
 
+	// DescendantNode
 	/**
 	 * @todo Should we special case repeat `readonly` state the same way
 	 * we do for `relevant`?
@@ -73,15 +108,6 @@ export class RepeatRange
 	 */
 	declare isSelfReadonly: Accessor<boolean>;
 
-	private readonly emptyRangeEvaluationContext: EvaluationContext & {
-		readonly contextNode: Comment;
-	};
-
-	/**
-	 * @see {@link isSelfRelevant}
-	 */
-	private readonly isEmptyRangeSelfRelevant: Accessor<boolean>;
-
 	/**
 	 * A repeat range does not exist in the primary instance tree. A `relevant`
 	 * expression applies to each {@link RepeatInstance} child of the repeat
@@ -125,8 +151,8 @@ export class RepeatRange
 		return this.isEmptyRangeSelfRelevant();
 	};
 
-	// RepeatRangeNode
-	readonly nodeType = 'repeat-range';
+	// BaseRepeatRangeNode
+	abstract override readonly nodeType: BaseRepeatRangeNodeType<Definition>;
 
 	/**
 	 * @todo RepeatRange*, RepeatInstance* (and RepeatTemplate*) all share the
@@ -161,16 +187,18 @@ export class RepeatRange
 	 * All of the above creates considerable ambiguity about where "repeat
 	 * appearances" should apply, under which circumstances.
 	 */
-	readonly appearances: RepeatRangeNodeAppearances;
+	abstract override readonly appearances: NodeAppearances<Definition>;
 
 	readonly currentState: MaterializedChildren<CurrentState<RepeatRangeStateSpec>, RepeatInstance>;
 
-	constructor(parent: GeneralParentNode, definition: RepeatRangeDefinition) {
+	abstract override readonly validationState: AncestorNodeValidationState;
+
+	constructor(parent: DescendantNodeParent<Definition>, definition: Definition) {
 		super(parent, definition);
 
-		this.appearances = definition.bodyElement.appearances;
+		const repeatRange = this as AnyDescendantNode as RepeatRange;
 
-		const childrenState = createChildrenState<RepeatRange, RepeatInstance>(this);
+		const childrenState = createChildrenState<RepeatRange, RepeatInstance>(repeatRange);
 
 		this.childrenState = childrenState;
 
@@ -179,7 +207,7 @@ export class RepeatRange
 		);
 		this.contextNode.append(this.anchorNode);
 
-		this.emptyRangeEvaluationContext = {
+		this.selfEvaluationContext = {
 			scope: this.scope,
 			evaluator: this.evaluator,
 			root: this.root,
@@ -187,15 +215,19 @@ export class RepeatRange
 			contextNode: this.anchorNode,
 
 			getSubscribableDependenciesByReference: (reference) => {
-				return this.getSubscribableDependenciesByReference(reference);
+				return repeatRange.getSubscribableDependenciesByReference(reference);
 			},
 		};
 
 		this.isEmptyRangeSelfRelevant = createComputedExpression(
-			this.emptyRangeEvaluationContext,
+			this.selfEvaluationContext,
 			definition.bind.relevant
 		);
 
+		const sharedStateOptions = {
+			clientStateFactory: this.engineConfig.stateFactory,
+		};
+
 		const state = createSharedNodeState(
 			this.scope,
 			{
@@ -210,9 +242,7 @@ export class RepeatRange
 				valueOptions: null,
 				value: null,
 			},
-			{
-				clientStateFactory: this.engineConfig.stateFactory,
-			}
+			sharedStateOptions
 		);
 
 		this.state = state;
@@ -222,15 +252,9 @@ export class RepeatRange
 			state.currentState,
 			childrenState
 		);
-
-		definition.instances.forEach((instanceDefinition, index) => {
-			const afterIndex = index - 1;
-
-			this.addInstances(afterIndex, 1, instanceDefinition);
-		});
 	}
 
-	private getLastIndex(): number {
+	protected getLastIndex(): number {
 		return this.engineState.children.length - 1;
 	}
 
@@ -242,66 +266,59 @@ export class RepeatRange
 		return this.engineState.children.indexOf(instance.nodeId);
 	}
 
-	addInstances(
-		afterIndex = this.getLastIndex(),
-		count = 1,
-		definition: RepeatDefinition = this.definition.template
-	): Root {
+	private createChildren(
+		afterIndex: number,
+		definitions: readonly RepeatDefinition[]
+	): readonly RepeatInstance[] {
 		return this.scope.runTask(() => {
-			let precedingInstance: RepeatInstance | null;
+			let initialPrecedingInstance: RepeatInstance | null;
 
 			if (afterIndex === -1) {
-				precedingInstance = null;
+				initialPrecedingInstance = null;
 			} else {
-				const instance = this.childrenState.getChildren()[afterIndex];
+				const instance = untrack(() => this.childrenState.getChildren()[afterIndex]);
 
 				if (instance == null) {
 					throw new Error(`No repeat instance at index ${afterIndex}`);
 				}
 
-				precedingInstance = instance;
+				initialPrecedingInstance = instance;
 			}
 
-			const precedingPrimaryInstanceNode = precedingInstance?.contextNode ?? this.anchorNode;
+			const repeatRange = this as AnyDescendantNode as RepeatRange;
 
-			const newInstance = new RepeatInstance(this, definition, {
-				precedingPrimaryInstanceNode,
-				precedingInstance,
-			});
-			const initialIndex = afterIndex + 1;
+			return definitions.reduce<RepeatInstance[]>((acc, definition) => {
+				const precedingInstance = acc[acc.length - 1] ?? initialPrecedingInstance;
+				const precedingPrimaryInstanceNode = precedingInstance?.contextNode ?? this.anchorNode;
+				const newInstance = new RepeatInstance(repeatRange, definition, {
+					precedingPrimaryInstanceNode,
+					precedingInstance,
+				});
 
-			this.childrenState.setChildren((currentInstances) => {
-				return insertAtIndex(currentInstances, initialIndex, newInstance);
-			});
+				acc.push(newInstance);
 
-			if (count > 1) {
-				return this.addInstances(initialIndex, count - 1);
-			}
+				return acc;
+			}, []);
+		});
+	}
 
-			return this.root;
+	protected addChildren(
+		afterIndex: number,
+		definitions: readonly RepeatDefinition[]
+	): readonly RepeatInstance[] {
+		return this.scope.runTask(() => {
+			const initialIndex = afterIndex + 1;
+			const newInstances = this.createChildren(afterIndex, definitions);
+
+			return this.childrenState.setChildren((currentInstances) => {
+				return insertAtIndex(currentInstances, initialIndex, newInstances);
+			});
 		});
 	}
 
-	/**
-	 * Removes the {@link RepeatInstance}s corresponding to the specified range of
-	 * indexes, and then removes those repeat instances from the repeat range's
-	 * own children state in that order:
-	 *
-	 * 1. Identify the set of {@link RepeatInstance}s to be removed.
-	 *
-	 * 2. For each {@link RepeatInstance} pending removal, perform that node's
-	 *    removal logic. @see {@link RepeatInstance.remove} for more detail.
-	 *
-	 * 3. Finalize update to the repeat range's own {@link childrenState},
-	 *    omitting those {@link RepeatInstance}s which were removed.
-	 *
-	 * This ordering ensures a consistent representation of state is established
-	 * prior to any downstream reactive updates, and ensures that removed nodes'
-	 * reactivity is cleaned up.
-	 */
-	removeInstances(startIndex: number, count = 1): Root {
+	protected removeChildren(startIndex: number, count: number): readonly RepeatInstance[] {
 		return this.scope.runTask(() => {
-			this.childrenState.setChildren((currentInstances) => {
+			return this.childrenState.setChildren((currentInstances) => {
 				const updatedInstances = currentInstances.slice();
 				const removedInstances = updatedInstances.splice(startIndex, count);
 
@@ -311,8 +328,6 @@ export class RepeatRange
 
 				return updatedInstances;
 			});
-
-			return this.root;
 		});
 	}
 

package/src/instance/{RepeatInstance.ts → repeat/RepeatInstance.ts}

@@ -4,25 +4,26 @@ import type {
 	RepeatDefinition,
 	RepeatInstanceNode,
 	RepeatInstanceNodeAppearances,
-} from '../client/RepeatInstanceNode.ts';
-import type { TextRange } from '../index.ts';
-import type { ChildrenState } from '../lib/reactivity/createChildrenState.ts';
-import { createChildrenState } from '../lib/reactivity/createChildrenState.ts';
-import type { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
-import { materializeCurrentStateChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
-import type { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
-import type { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
-import type { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
-import { createSharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
-import { createNodeLabel } from '../lib/reactivity/text/createNodeLabel.ts';
-import type { RepeatRange } from './RepeatRange.ts';
-import type { DescendantNodeSharedStateSpec } from './abstract/DescendantNode.ts';
-import { DescendantNode } from './abstract/DescendantNode.ts';
-import { buildChildren } from './children.ts';
-import type { AnyChildNode, GeneralChildNode } from './hierarchy.ts';
-import type { NodeID } from './identity.ts';
-import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
-import type { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
+} from '../../client/repeat/RepeatInstanceNode.ts';
+import type { TextRange } from '../../client/TextRange.ts';
+import type { AncestorNodeValidationState } from '../../client/validation.ts';
+import type { ChildrenState } from '../../lib/reactivity/createChildrenState.ts';
+import { createChildrenState } from '../../lib/reactivity/createChildrenState.ts';
+import type { MaterializedChildren } from '../../lib/reactivity/materializeCurrentStateChildren.ts';
+import { materializeCurrentStateChildren } from '../../lib/reactivity/materializeCurrentStateChildren.ts';
+import type { CurrentState } from '../../lib/reactivity/node-state/createCurrentState.ts';
+import type { EngineState } from '../../lib/reactivity/node-state/createEngineState.ts';
+import type { SharedNodeState } from '../../lib/reactivity/node-state/createSharedNodeState.ts';
+import { createSharedNodeState } from '../../lib/reactivity/node-state/createSharedNodeState.ts';
+import { createNodeLabel } from '../../lib/reactivity/text/createNodeLabel.ts';
+import { createAggregatedViolations } from '../../lib/reactivity/validation/createAggregatedViolations.ts';
+import type { DescendantNodeSharedStateSpec } from '../abstract/DescendantNode.ts';
+import { DescendantNode } from '../abstract/DescendantNode.ts';
+import { buildChildren } from '../children.ts';
+import type { AnyChildNode, GeneralChildNode, RepeatRange } from '../hierarchy.ts';
+import type { NodeID } from '../identity.ts';
+import type { EvaluationContext } from '../internal-api/EvaluationContext.ts';
+import type { SubscribableDependency } from '../internal-api/SubscribableDependency.ts';
 
 export type { RepeatDefinition };
 
@@ -87,6 +88,7 @@ export class RepeatInstance
 		CurrentState<RepeatInstanceStateSpec>,
 		GeneralChildNode
 	>;
+	readonly validationState: AncestorNodeValidationState;
 
 	constructor(
 		override readonly parent: RepeatRange,
@@ -116,6 +118,10 @@ export class RepeatInstance
 
 		this.currentIndex = currentIndex;
 
+		const sharedStateOptions = {
+			clientStateFactory: this.engineConfig.stateFactory,
+		};
+
 		const state = createSharedNodeState(
 			this.scope,
 			{
@@ -131,9 +137,7 @@ export class RepeatInstance
 				valueOptions: null,
 				value: null,
 			},
-			{
-				clientStateFactory: this.engineConfig.stateFactory,
-			}
+			sharedStateOptions
 		);
 
 		this.state = state;
@@ -166,6 +170,7 @@ export class RepeatInstance
 		});
 
 		childrenState.setChildren(buildChildren(this));
+		this.validationState = createAggregatedViolations(this, sharedStateOptions);
 	}
 
 	protected override initializeContextNode(parentContextNode: Element, nodeName: string): Element {

package/src/instance/repeat/RepeatRangeControlled.ts

@@ -0,0 +1,82 @@
+import { createComputed } from 'solid-js';
+import type { RepeatRangeNodeAppearances } from '../../client/repeat/BaseRepeatRangeNode.ts';
+import type { RepeatRangeControlledNode } from '../../client/repeat/RepeatRangeControlledNode.ts';
+import type { AncestorNodeValidationState } from '../../client/validation.ts';
+import { createComputedExpression } from '../../lib/reactivity/createComputedExpression.ts';
+import { createAggregatedViolations } from '../../lib/reactivity/validation/createAggregatedViolations.ts';
+import type { ControlledRepeatRangeDefinition } from '../../parse/model/RepeatRangeDefinition.ts';
+import type { GeneralParentNode } from '../hierarchy.ts';
+import type { EvaluationContext } from '../internal-api/EvaluationContext.ts';
+import type { SubscribableDependency } from '../internal-api/SubscribableDependency.ts';
+import { BaseRepeatRange } from './BaseRepeatRange.ts';
+import type { RepeatDefinition } from './RepeatInstance.ts';
+
+export class RepeatRangeControlled
+	extends BaseRepeatRange<ControlledRepeatRangeDefinition>
+	implements RepeatRangeControlledNode, EvaluationContext, SubscribableDependency
+{
+	// RepeatRangeControlledNode
+	readonly nodeType = 'repeat-range:controlled';
+
+	readonly appearances: RepeatRangeNodeAppearances;
+
+	readonly validationState: AncestorNodeValidationState;
+
+	constructor(parent: GeneralParentNode, definition: ControlledRepeatRangeDefinition) {
+		super(parent, definition);
+
+		this.appearances = definition.bodyElement.appearances;
+
+		this.initializeControlledChildrenState(definition);
+
+		this.validationState = createAggregatedViolations(this, {
+			clientStateFactory: this.engineConfig.stateFactory,
+		});
+	}
+
+	private initializeControlledChildrenState(definition: ControlledRepeatRangeDefinition): void {
+		this.scope.runTask(() => {
+			const { count, instances, template } = definition;
+			const computeCount = createComputedExpression(this.selfEvaluationContext, count);
+
+			createComputed<number>((previousCount) => {
+				let currentCount = computeCount();
+
+				if (Number.isFinite(currentCount) && currentCount < 0) {
+					currentCount = 0;
+				}
+
+				if (
+					currentCount === previousCount ||
+					// TODO: the intent of this check is to defer a count update when the
+					// count expression produces a blank value. This "feels right" when
+					// the count is directly controlled by the user (i.e. entering a
+					// number in an input), but probably does not make sense in every
+					// scenario! For instance, when a referenced node's relevance changes.
+					Number.isNaN(currentCount)
+				) {
+					return previousCount;
+				}
+
+				if (currentCount > previousCount) {
+					const delta = currentCount - previousCount;
+					const definitions = Array<RepeatDefinition>(delta)
+						.fill(template)
+						.map((baseDefinition, index) => {
+							const instanceIndex = previousCount + index;
+
+							return instances[instanceIndex] ?? baseDefinition;
+						});
+
+					this.addChildren(previousCount - 1, definitions);
+				} else {
+					const delta = previousCount - currentCount;
+
+					this.removeChildren(currentCount, delta);
+				}
+
+				return currentCount;
+			}, 0);
+		});
+	}
+}

package/src/instance/repeat/RepeatRangeUncontrolled.ts

@@ -0,0 +1,67 @@
+import type { RepeatRangeNodeAppearances } from '../../client/repeat/BaseRepeatRangeNode.ts';
+import type { RepeatRangeUncontrolledNode } from '../../client/repeat/RepeatRangeUncontrolledNode.ts';
+import type { AncestorNodeValidationState } from '../../client/validation.ts';
+import { createAggregatedViolations } from '../../lib/reactivity/validation/createAggregatedViolations.ts';
+import type { UncontrolledRepeatRangeDefinition } from '../../parse/model/RepeatRangeDefinition.ts';
+import type { GeneralParentNode } from '../hierarchy.ts';
+import type { EvaluationContext } from '../internal-api/EvaluationContext.ts';
+import type { SubscribableDependency } from '../internal-api/SubscribableDependency.ts';
+import type { Root } from '../Root.ts';
+import { BaseRepeatRange } from './BaseRepeatRange.ts';
+import { RepeatInstance } from './RepeatInstance.ts';
+
+export class RepeatRangeUncontrolled
+	extends BaseRepeatRange<UncontrolledRepeatRangeDefinition>
+	implements RepeatRangeUncontrolledNode, EvaluationContext, SubscribableDependency
+{
+	// RepeatRangeUncontrolledNode
+	readonly nodeType = 'repeat-range:uncontrolled';
+
+	readonly appearances: RepeatRangeNodeAppearances;
+
+	readonly validationState: AncestorNodeValidationState;
+
+	constructor(parent: GeneralParentNode, definition: UncontrolledRepeatRangeDefinition) {
+		super(parent, definition);
+
+		this.appearances = definition.bodyElement.appearances;
+
+		this.addChildren(-1, definition.instances);
+
+		this.validationState = createAggregatedViolations(this, {
+			clientStateFactory: this.engineConfig.stateFactory,
+		});
+	}
+
+	// RepeatRangeUncontrolledNode
+	addInstances(afterIndex = this.getLastIndex(), count = 1): Root {
+		const definitions = Array(count).fill(this.definition.template);
+
+		this.addChildren(afterIndex, definitions);
+
+		return this.root;
+	}
+
+	/**
+	 * Removes the {@link RepeatInstance}s corresponding to the specified range of
+	 * indexes, and then removes those repeat instances from the repeat range's
+	 * own children state in that order:
+	 *
+	 * 1. Identify the set of {@link RepeatInstance}s to be removed.
+	 *
+	 * 2. For each {@link RepeatInstance} pending removal, perform that node's
+	 *    removal logic. @see {@link RepeatInstance.remove} for more detail.
+	 *
+	 * 3. Finalize update to the repeat range's own {@link childrenState},
+	 *    omitting those {@link RepeatInstance}s which were removed.
+	 *
+	 * This ordering ensures a consistent representation of state is established
+	 * prior to any downstream reactive updates, and ensures that removed nodes'
+	 * reactivity is cleaned up.
+	 */
+	removeInstances(startIndex: number, count = 1): Root {
+		this.removeChildren(startIndex, count);
+
+		return this.root;
+	}
+}

package/src/instance/text/TextRange.ts

@@ -1,9 +1,14 @@
-import type { TextRange as ClientTextRange, TextChunk } from '../../client/TextRange.ts';
+import type {
+	TextRange as ClientTextRange,
+	TextChunk,
+	TextOrigin,
+	TextRole,
+} from '../../client/TextRange.ts';
 import { FormattedTextStub } from './FormattedTextStub.ts';
 
-export type TextRole = 'hint' | 'label';
-
-export class TextRange<Role extends TextRole> implements ClientTextRange<Role> {
+export class TextRange<Role extends TextRole, Origin extends TextOrigin>
+	implements ClientTextRange<Role, Origin>
+{
 	*[Symbol.iterator]() {
 		yield* this.chunks;
 	}
@@ -17,6 +22,7 @@ export class TextRange<Role extends TextRole> implements ClientTextRange<Role> {
 	}
 
 	constructor(
+		readonly origin: Origin,
 		readonly role: Role,
 		protected readonly chunks: readonly TextChunk[]
 	) {}

package/src/instance/unsupported/RangeControl.ts

@@ -0,0 +1,5 @@
+import { UnsupportedControl } from '../abstract/UnsupportedControl.ts';
+
+export class RangeControl extends UnsupportedControl<'range'> {
+	readonly nodeType = 'range';
+}

package/src/instance/unsupported/RankControl.ts

@@ -0,0 +1,5 @@
+import { UnsupportedControl } from '../abstract/UnsupportedControl.ts';
+
+export class RankControl extends UnsupportedControl<'rank'> {
+	readonly nodeType = 'rank';
+}

package/src/instance/unsupported/UploadControl.ts

@@ -0,0 +1,5 @@
+import { UnsupportedControl } from '../abstract/UnsupportedControl.ts';
+
+export class UploadControl extends UnsupportedControl<'upload'> {
+	readonly nodeType = 'upload';
+}