@getodk/xforms-engine 0.5.0 → 0.6.0

package/src/instance/Root.ts

@@ -12,7 +12,7 @@ import type { SubmissionResult } from '../client/submission/SubmissionResult.ts'
 import type { SubmissionState } from '../client/submission/SubmissionState.ts';
 import type { AncestorNodeValidationState } from '../client/validation.ts';
 import type { XFormsXPathElement } from '../integration/xpath/adapter/XFormsXPathNode.ts';
-import { createParentNodeSubmissionState } from '../lib/client-reactivity/submission/createParentNodeSubmissionState.ts';
+import { createRootSubmissionState } from '../lib/client-reactivity/submission/createRootSubmissionState.ts';
 import type { ChildrenState } from '../lib/reactivity/createChildrenState.ts';
 import { createChildrenState } from '../lib/reactivity/createChildrenState.ts';
 import type { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
@@ -76,6 +76,7 @@ export class Root
 	// RootNode
 	readonly nodeType = 'root';
 	readonly appearances = null;
+	readonly nodeOptions = null;
 	readonly classes: BodyClassList;
 	readonly currentState: MaterializedChildren<CurrentState<RootStateSpec>, GeneralChildNode>;
 	readonly validationState: AncestorNodeValidationState;
@@ -136,7 +137,7 @@ export class Root
 
 		childrenState.setChildren(buildChildren(this));
 		this.validationState = createAggregatedViolations(this, sharedStateOptions);
-		this.submissionState = createParentNodeSubmissionState(this);
+		this.submissionState = createRootSubmissionState(this);
 	}
 
 	getChildren(): readonly GeneralChildNode[] {

package/src/instance/SelectControl.ts

@@ -0,0 +1,219 @@
+import { XPathNodeKindKey } from '@getodk/xpath';
+import type { Accessor } from 'solid-js';
+import { createMemo } from 'solid-js';
+import type {
+	SelectDefinition,
+	SelectItem,
+	SelectNode,
+	SelectNodeAppearances,
+	SelectValueOptions,
+} from '../client/SelectNode.ts';
+import type { TextRange } from '../client/TextRange.ts';
+import type { ValueType } from '../client/ValueType.ts';
+import { SelectValueTypeError } from '../error/SelectValueTypeError.ts';
+import type { XFormsXPathElement } from '../integration/xpath/adapter/XFormsXPathNode.ts';
+import { getSelectCodec } from '../lib/codecs/getSelectCodec.ts';
+import { createItemCollection } from '../lib/reactivity/createItemCollection.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 { createFieldHint } from '../lib/reactivity/text/createFieldHint.ts';
+import { createNodeLabel } from '../lib/reactivity/text/createNodeLabel.ts';
+import type { SimpleAtomicState } from '../lib/reactivity/types.ts';
+import type { SelectType } from '../parse/body/control/SelectControlDefinition.ts';
+import type { Root } from './Root.ts';
+import type { ValueNodeStateSpec } from './abstract/ValueNode.ts';
+import { ValueNode } from './abstract/ValueNode.ts';
+import type { GeneralParentNode } from './hierarchy.ts';
+import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
+import type { ValidationContext } from './internal-api/ValidationContext.ts';
+import type { ClientReactiveSubmittableValueNode } from './internal-api/submission/ClientReactiveSubmittableValueNode.ts';
+
+export type AnySelectDefinition = {
+	[V in ValueType]: SelectDefinition<V>;
+}[ValueType];
+
+type AssertSupportedSelectValueType = (
+	definition: AnySelectDefinition
+) => asserts definition is SelectDefinition<'string'>;
+
+const assertSupportedSelectValueType: AssertSupportedSelectValueType = (definition) => {
+	if (definition.valueType !== 'string') {
+		throw new SelectValueTypeError(definition);
+	}
+};
+
+type SelectItemMap = ReadonlyMap<string, SelectItem>;
+
+interface SelectControlStateSpec extends ValueNodeStateSpec<readonly string[]> {
+	readonly label: Accessor<TextRange<'label'> | null>;
+	readonly hint: Accessor<TextRange<'hint'> | null>;
+	readonly valueOptions: Accessor<SelectValueOptions>;
+}
+
+export class SelectControl
+	extends ValueNode<'string', SelectDefinition<'string'>, readonly string[], readonly string[]>
+	implements
+		SelectNode,
+		XFormsXPathElement,
+		EvaluationContext,
+		ValidationContext,
+		ClientReactiveSubmittableValueNode
+{
+	static from(parent: GeneralParentNode, definition: SelectDefinition): SelectControl;
+	static from(parent: GeneralParentNode, definition: AnySelectDefinition): SelectControl {
+		assertSupportedSelectValueType(definition);
+
+		return new this(parent, definition);
+	}
+
+	private readonly mapOptionsByValue: Accessor<SelectItemMap>;
+
+	protected override readonly getInstanceValue: Accessor<string>;
+
+	// XFormsXPathElement
+	override readonly [XPathNodeKindKey] = 'element';
+
+	// InstanceNode
+	protected readonly state: SharedNodeState<SelectControlStateSpec>;
+	protected readonly engineState: EngineState<SelectControlStateSpec>;
+
+	// SelectNode
+	readonly nodeType = 'select';
+	readonly selectType: SelectType;
+	readonly appearances: SelectNodeAppearances;
+	readonly nodeOptions = null;
+	readonly currentState: CurrentState<SelectControlStateSpec>;
+
+	private constructor(parent: GeneralParentNode, definition: SelectDefinition<'string'>) {
+		const codec = getSelectCodec(definition);
+
+		super(parent, definition, codec);
+
+		this.appearances = definition.bodyElement.appearances;
+		this.selectType = definition.bodyElement.type;
+
+		const valueOptions = createItemCollection(this);
+
+		const mapOptionsByValue: Accessor<SelectItemMap> = this.scope.runTask(() => {
+			return createMemo(() => {
+				return new Map(valueOptions().map((item) => [item.value, item]));
+			});
+		});
+
+		this.mapOptionsByValue = mapOptionsByValue;
+
+		const baseValueState = this.valueState;
+		const [baseGetValue, setValue] = baseValueState;
+		const getValue = this.scope.runTask(() => {
+			return createMemo(() => {
+				const optionsByValue = mapOptionsByValue();
+
+				return baseGetValue().filter((value) => {
+					return optionsByValue.has(value);
+				});
+			});
+		});
+		const valueState: SimpleAtomicState<readonly string[]> = [getValue, setValue];
+
+		this.getInstanceValue = this.scope.runTask(() => {
+			return createMemo(() => {
+				return codec.encodeValue(getValue());
+			});
+		});
+
+		const sharedStateOptions = {
+			clientStateFactory: this.engineConfig.stateFactory,
+		};
+
+		const state = createSharedNodeState(
+			this.scope,
+			{
+				reference: this.contextReference,
+				readonly: this.isReadonly,
+				relevant: this.isRelevant,
+				required: this.isRequired,
+
+				label: createNodeLabel(this, definition),
+				hint: createFieldHint(this, definition),
+				children: null,
+				valueOptions,
+				value: valueState,
+				instanceValue: this.getInstanceValue,
+			},
+			sharedStateOptions
+		);
+
+		this.state = state;
+		this.engineState = state.engineState;
+		this.currentState = state.currentState;
+	}
+
+	/**
+	 * Filters {@link values} to include only those values which are currently
+	 * available in the mapping produced by {@link mapOptionsByValue}, i.e. within
+	 * a potentially filtered itemset.
+	 *
+	 * Note: this method effectively produces an intersection of
+	 * {@link sourceValues} and {@link values}. **Importantly**, ordering of the
+	 * results is deterministic, preserving the order of values as yielded _by
+	 * {@link sourceValues}_.
+	 *
+	 * At time of writing, there are several tests (in `@getodk/scenario`, ported
+	 * from JavaRosa) which expect the values of a `<select>` to match the order
+	 * they appear in the control's (potentially filtered) `<itemset>` (or list of
+	 * `<item>`s, for forms defining those inline).
+	 *
+	 * @todo The `<odk:rank>` control, having semantics very similar to
+	 * `<select>`, will likely perform similar filtering logic. However, one of
+	 * the important distinctions between these controls is that `<odk:rank>`
+	 * exists explicitly to control the order of values. It's quite likely that
+	 * would be achieved by invoking the same logic with the parameter order
+	 * reversed.
+	 */
+	private filterValues(
+		sourceValues: Iterable<string>,
+		values: Iterable<string>
+	): readonly string[] {
+		const selectedValues = new Set(values);
+
+		return Array.from(sourceValues).filter((sourceValue) => {
+			return selectedValues.has(sourceValue);
+		});
+	}
+
+	// SelectNode
+	getValueOption(value: string): SelectItem | null {
+		// Note: this method is a client-facing convenience API for reading state,
+		// so it **MUST** read from client-reactive state!
+		const valueOption = this.currentState.valueOptions.find((item) => {
+			return item.value === value;
+		});
+
+		return valueOption ?? null;
+	}
+
+	isSelected(value: string): boolean {
+		// Note: this method is a client-facing convenience API for reading state,
+		// so it **MUST** read from client-reactive state!
+		return this.currentState.value.includes(value);
+	}
+
+	selectValue(value: string | null): Root {
+		if (value == null) {
+			return this.selectValues([]);
+		}
+
+		return this.selectValues([value]);
+	}
+
+	selectValues(values: readonly string[]): Root {
+		const sourceValues = this.mapOptionsByValue().keys();
+		const effectiveValues = this.filterValues(sourceValues, values);
+
+		this.setValueState(effectiveValues);
+
+		return this.root;
+	}
+}

package/src/instance/Subtree.ts

@@ -49,6 +49,7 @@ export class Subtree
 	// SubtreeNode
 	readonly nodeType = 'subtree';
 	readonly appearances = null;
+	readonly nodeOptions = null;
 	readonly currentState: MaterializedChildren<CurrentState<SubtreeStateSpec>, GeneralChildNode>;
 	readonly validationState: AncestorNodeValidationState;
 	readonly submissionState: SubmissionState;

package/src/instance/TriggerControl.ts

@@ -2,51 +2,61 @@ import { XPathNodeKindKey } from '@getodk/xpath';
 import type { Accessor } from 'solid-js';
 import type { TextRange } from '../client/TextRange.ts';
 import type { TriggerNode, TriggerNodeDefinition } from '../client/TriggerNode.ts';
-import type { SubmissionState } from '../client/submission/SubmissionState.ts';
-import type { AnyViolation, LeafNodeValidationState } from '../client/validation.ts';
+import type { ValueType } from '../client/ValueType.ts';
+import { ErrorProductionDesignPendingError } from '../error/ErrorProductionDesignPendingError.ts';
 import type { XFormsXPathElement } from '../integration/xpath/adapter/XFormsXPathNode.ts';
-import { createLeafNodeSubmissionState } from '../lib/client-reactivity/submission/createLeafNodeSubmissionState.ts';
-import { createValueState } from '../lib/reactivity/createValueState.ts';
+import type { TriggerInputValue, TriggerRuntimeValue } from '../lib/codecs/TriggerCodec.ts';
+import { TriggerCodec } from '../lib/codecs/TriggerCodec.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 { createFieldHint } from '../lib/reactivity/text/createFieldHint.ts';
 import { createNodeLabel } from '../lib/reactivity/text/createNodeLabel.ts';
-import type { SimpleAtomicState } from '../lib/reactivity/types.ts';
-import type { SharedValidationState } from '../lib/reactivity/validation/createValidation.ts';
-import { createValidationState } from '../lib/reactivity/validation/createValidation.ts';
 import type { UnknownAppearanceDefinition } from '../parse/body/appearance/unknownAppearanceParser.ts';
 import type { Root } from './Root.ts';
-import type { DescendantNodeStateSpec } from './abstract/DescendantNode.ts';
-import { DescendantNode } from './abstract/DescendantNode.ts';
+import { ValueNode, type ValueNodeStateSpec } from './abstract/ValueNode.ts';
 import type { GeneralParentNode } from './hierarchy.ts';
 import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
 import type { ValidationContext } from './internal-api/ValidationContext.ts';
-import type { ValueContext } from './internal-api/ValueContext.ts';
-import type { ClientReactiveSubmittableLeafNode } from './internal-api/submission/ClientReactiveSubmittableLeafNode.ts';
+import type { ClientReactiveSubmittableValueNode } from './internal-api/submission/ClientReactiveSubmittableValueNode.ts';
 
-interface TriggerControlStateSpec extends DescendantNodeStateSpec<boolean> {
+interface TriggerControlStateSpec extends ValueNodeStateSpec<TriggerRuntimeValue> {
 	readonly label: Accessor<TextRange<'label'> | null>;
 	readonly hint: Accessor<TextRange<'hint'> | null>;
-	readonly children: null;
-	readonly value: SimpleAtomicState<boolean>;
 	readonly valueOptions: null;
 }
 
-const TRIGGER_ASSIGNED_VALUE = 'OK';
+type AnyTriggerNodeDefinition = {
+	[V in ValueType]: TriggerNodeDefinition<V>;
+}[ValueType];
+
+const codec = new TriggerCodec();
 
 export class TriggerControl
-	extends DescendantNode<TriggerNodeDefinition, TriggerControlStateSpec, GeneralParentNode, null>
+	extends ValueNode<
+		'string',
+		TriggerNodeDefinition<'string'>,
+		TriggerRuntimeValue,
+		TriggerInputValue
+	>
 	implements
 		TriggerNode,
 		XFormsXPathElement,
 		EvaluationContext,
 		ValidationContext,
-		ValueContext<boolean>,
-		ClientReactiveSubmittableLeafNode<boolean>
+		ClientReactiveSubmittableValueNode
 {
-	private readonly validation: SharedValidationState;
+	static from(parent: GeneralParentNode, definition: TriggerNodeDefinition): TriggerControl;
+	static from(parent: GeneralParentNode, definition: AnyTriggerNodeDefinition): TriggerControl {
+		if (definition.valueType !== 'string') {
+			throw new ErrorProductionDesignPendingError(
+				`Unsupported trigger value type: ${definition.valueType}`
+			);
+		}
+
+		return new this(parent, definition);
+	}
 
 	// XFormsXPathElement
 	override readonly [XPathNodeKindKey] = 'element';
@@ -58,42 +68,13 @@ export class TriggerControl
 	// TriggerNode
 	readonly nodeType = 'trigger';
 	readonly appearances: UnknownAppearanceDefinition;
+	readonly nodeOptions = null;
 	readonly currentState: CurrentState<TriggerControlStateSpec>;
 
-	get validationState(): LeafNodeValidationState {
-		return this.validation.currentState;
-	}
-
-	readonly submissionState: SubmissionState;
-
-	// ValueContext
-	override readonly contextNode = this;
-	readonly encodeValue: (runtimeValue: boolean) => string;
-	readonly decodeValue: (instanceValue: string) => boolean;
-
-	constructor(parent: GeneralParentNode, definition: TriggerNodeDefinition) {
-		super(parent, definition);
+	private constructor(parent: GeneralParentNode, definition: TriggerNodeDefinition<'string'>) {
+		super(parent, definition, codec);
 
 		this.appearances = definition.bodyElement.appearances;
-		this.encodeValue = (runtimeValue) => {
-			return runtimeValue ? TRIGGER_ASSIGNED_VALUE : '';
-		};
-		this.decodeValue = (instanceValue) => {
-			const value = instanceValue.trim();
-
-			switch (value) {
-				case TRIGGER_ASSIGNED_VALUE:
-					return true;
-
-				case '':
-					return false;
-
-				// TODO (robustness principle): Case insensitivity? Handle
-				// XPath-semantic booleans?? Other known/common equivalents?
-				default:
-					throw new Error(`Unexpected trigger value: ${value}`);
-			}
-		};
 
 		const sharedStateOptions = {
 			clientStateFactory: this.engineConfig.stateFactory,
@@ -111,7 +92,8 @@ export class TriggerControl
 				hint: createFieldHint(this, definition),
 				children: null,
 				valueOptions: null,
-				value: createValueState(this),
+				value: this.valueState,
+				instanceValue: this.getInstanceValue,
 			},
 			sharedStateOptions
 		);
@@ -119,32 +101,11 @@ export class TriggerControl
 		this.state = state;
 		this.engineState = state.engineState;
 		this.currentState = state.currentState;
-		this.validation = createValidationState(this, sharedStateOptions);
-		this.submissionState = createLeafNodeSubmissionState(this);
-	}
-
-	// XFormsXPathElement
-	override getXPathValue(): string {
-		return this.encodeValue(this.engineState.value);
-	}
-
-	// ValidationContext
-	getViolation(): AnyViolation | null {
-		return this.validation.engineState.violation;
-	}
-
-	isBlank(): boolean {
-		return this.engineState.value == null;
-	}
-
-	// InstanceNode
-	getChildren(): readonly [] {
-		return [];
 	}
 
 	// TriggerNode
-	setValue(value: boolean): Root {
-		this.state.setProperty('value', value);
+	setValue(value: TriggerInputValue): Root {
+		this.setValueState(value);
 
 		return this.root;
 	}

package/src/instance/abstract/DescendantNode.ts

@@ -13,7 +13,6 @@ import { XFORMS_XPATH_NODE_RANGE_KIND } from '../../integration/xpath/adapter/XF
 import type { EngineXPathEvaluator } from '../../integration/xpath/EngineXPathEvaluator.ts';
 import { createComputedExpression } from '../../lib/reactivity/createComputedExpression.ts';
 import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
-import type { AnyDescendantNodeDefinition } from '../../parse/model/DescendentNodeDefinition.ts';
 import type { AnyNodeDefinition } from '../../parse/model/NodeDefinition.ts';
 import type { AnyChildNode, AnyParentNode, RepeatRange } from '../hierarchy.ts';
 import type { EvaluationContext } from '../internal-api/EvaluationContext.ts';
@@ -35,11 +34,7 @@ export type DescendantNodeStateSpec<Value = never> =
 	& InstanceNodeStateSpec<Value>
 	& DescendantNodeSharedStateSpec;
 
-// prettier-ignore
-export type DescendantNodeDefinition = Extract<
-	AnyNodeDefinition,
-	AnyDescendantNodeDefinition
->;
+export type DescendantNodeDefinition = AnyNodeDefinition;
 
 export type AnyDescendantNode = DescendantNode<
 	DescendantNodeDefinition,

package/src/instance/abstract/InstanceNode.ts

@@ -34,6 +34,12 @@ export interface BaseEngineNode extends Omit<BaseNode, 'nodeType'> {
 	readonly nodeType: EngineInstanceNodeType;
 }
 
+// prettier-ignore
+export type InstanceNodeValueOptionsStateSpec =
+	| Accessor<null>
+	| Accessor<readonly unknown[]>
+	| null
+
 export interface InstanceNodeStateSpec<Value = never> {
 	readonly reference: Accessor<string> | string;
 	readonly readonly: Accessor<boolean> | boolean;
@@ -42,7 +48,7 @@ export interface InstanceNodeStateSpec<Value = never> {
 	readonly label: Accessor<TextRange<'label'> | null> | null;
 	readonly hint: Accessor<TextRange<'hint'> | null> | null;
 	readonly children: Accessor<readonly FormNodeID[]> | null;
-	readonly valueOptions: Accessor<null> | Accessor<readonly unknown[]> | null;
+	readonly valueOptions: InstanceNodeValueOptionsStateSpec;
 	readonly value: Signal<Value> | SimpleAtomicState<Value> | null;
 }
 
@@ -136,6 +142,8 @@ export abstract class InstanceNode<
 
 	abstract readonly appearances: NodeAppearances<Definition>;
 
+	abstract readonly nodeOptions: object | null;
+
 	abstract readonly currentState: InstanceNodeCurrentState<Spec, Child>;
 
 	abstract readonly validationState: NodeValidationState;
@@ -161,7 +169,7 @@ export abstract class InstanceNode<
 			);
 		}
 
-		return `${parent.contextReference()}/${definition.nodeName}`;
+		return `${parent.contextReference()}/${definition.qualifiedName.getPrefixedName()}`;
 	};
 
 	// EvaluationContext: node-specific

package/src/instance/abstract/UnsupportedControl.ts

@@ -92,6 +92,7 @@ export abstract class UnsupportedControl<Type extends UnsupportedControlNodeType
 	abstract override readonly nodeType: Type;
 
 	readonly appearances: UnknownAppearanceDefinition;
+	readonly nodeOptions = null;
 	readonly currentState: CurrentState<UnsupportedControlStateSpec>;
 
 	get validationState(): LeafNodeValidationState {

package/src/instance/abstract/ValueNode.ts

@@ -35,7 +35,6 @@ export type ValueNodeDefinition<V extends ValueType> = LeafNodeDefinition<V>;
 
 export interface ValueNodeStateSpec<RuntimeValue> extends DescendantNodeStateSpec<RuntimeValue> {
 	readonly children: null;
-	readonly valueOptions: null;
 	readonly value: SimpleAtomicState<RuntimeValue>;
 	readonly instanceValue: Accessor<string>;
 }
@@ -103,7 +102,9 @@ export abstract class ValueNode<
 
 		this.getInstanceValue = getInstanceValue;
 		this.setValueState = setValueState;
-		this.getXPathValue = getInstanceValue;
+		this.getXPathValue = () => {
+			return this.getInstanceValue();
+		};
 		this.valueState = valueState;
 		this.validation = createValidationState(this, {
 			clientStateFactory: this.engineConfig.stateFactory,

package/src/instance/children.ts

@@ -2,28 +2,32 @@ import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
 import type { GroupDefinition } from '../client/GroupNode.ts';
 import type { InputDefinition } from '../client/InputNode.ts';
 import type { ModelValueDefinition } from '../client/ModelValueNode.ts';
+import type { SelectDefinition } from '../client/SelectNode.ts';
 import type { SubtreeDefinition } from '../client/SubtreeNode.ts';
 import type { TriggerNodeDefinition } from '../client/TriggerNode.ts';
-import type { RangeNodeDefinition } from '../client/unsupported/RangeNode.ts';
-import type { RankNodeDefinition } from '../client/unsupported/RankNode.ts';
-import type { UnsupportedControlDefinition } from '../client/unsupported/UnsupportedControlNode.ts';
+import type { RankDefinition } from '../client/RankNode.ts';
 import type { UploadNodeDefinition } from '../client/unsupported/UploadNode.ts';
+import { ErrorProductionDesignPendingError } from '../error/ErrorProductionDesignPendingError.ts';
 import type { LeafNodeDefinition } from '../parse/model/LeafNodeDefinition.ts';
 import { NoteNodeDefinition } from '../parse/model/NoteNodeDefinition.ts';
+import type {
+	AnyRangeNodeDefinition,
+	RangeLeafNodeDefinition,
+} from '../parse/model/RangeNodeDefinition.ts';
+import { RangeNodeDefinition } from '../parse/model/RangeNodeDefinition.ts';
 import type { SubtreeDefinition as ModelSubtreeDefinition } from '../parse/model/SubtreeDefinition.ts';
 import { Group } from './Group.ts';
 import type { GeneralChildNode, GeneralParentNode } from './hierarchy.ts';
 import { InputControl } from './InputControl.ts';
 import { ModelValue } from './ModelValue.ts';
 import { Note } from './Note.ts';
+import { RangeControl } from './RangeControl.ts';
 import { RepeatRangeControlled } from './repeat/RepeatRangeControlled.ts';
 import { RepeatRangeUncontrolled } from './repeat/RepeatRangeUncontrolled.ts';
-import type { SelectFieldDefinition } from './SelectField.ts';
-import { SelectField } from './SelectField.ts';
+import { SelectControl } from './SelectControl.ts';
 import { Subtree } from './Subtree.ts';
 import { TriggerControl } from './TriggerControl.ts';
-import { RangeControl } from './unsupported/RangeControl.ts';
-import { RankControl } from './unsupported/RankControl.ts';
+import { RankControl } from './RankControl.ts';
 import { UploadControl } from './unsupported/UploadControl.ts';
 
 const isSubtreeDefinition = (
@@ -32,16 +36,16 @@ const isSubtreeDefinition = (
 	return definition.bodyElement == null;
 };
 
-type AnyUnsupportedControlDefinition =
-	| RangeNodeDefinition
-	| RankNodeDefinition
-	| UploadNodeDefinition;
+// prettier-ignore
+type AnyUnsupportedControlDefinition = UploadNodeDefinition;
 
 // prettier-ignore
 type ControlNodeDefinition =
 	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
 	| InputDefinition
-	| SelectFieldDefinition
+	| RangeLeafNodeDefinition
+	| SelectDefinition
+	| RankDefinition
 	| TriggerNodeDefinition
 	| AnyUnsupportedControlDefinition;
 
@@ -57,22 +61,57 @@ const isInputDefinition = (definition: ControlNodeDefinition): definition is Inp
 	return definition.bodyElement.type === 'input';
 };
 
-const isSelectFieldDefinition = (
-	definition: ControlNodeDefinition
-): definition is SelectFieldDefinition => {
+const isSelectDefinition = (definition: ControlNodeDefinition): definition is SelectDefinition => {
 	return definition.bodyElement.type === 'select' || definition.bodyElement.type === 'select1';
 };
 
-const isRangeNodeDefinition = (
-	definition: UnsupportedControlDefinition
-): definition is RangeNodeDefinition => {
+const isRankDefinition = (definition: ControlNodeDefinition): definition is RankDefinition => {
+	return definition.bodyElement.type === 'rank';
+};
+
+const isRangeLeafNodeDefinition = (
+	definition: ControlNodeDefinition
+): definition is RangeLeafNodeDefinition => {
 	return definition.bodyElement.type === 'range';
 };
 
-const isRankNodeDefinition = (
-	definition: UnsupportedControlDefinition
-): definition is RankNodeDefinition => {
-	return definition.bodyElement.type === 'rank';
+type AssertRangeNodeDefinition = (
+	definition: RangeLeafNodeDefinition
+) => asserts definition is AnyRangeNodeDefinition;
+
+/**
+ * We need some way to narrow the base {@link RangeLeafNodeDefinition} type to
+ * {@link RankNodeDefinition} type.
+ *
+ * At time of writing, we know there is no code path to produce the broader
+ * type, but appeasing the type checker for it will help guard against
+ * introducing one. (And it would have caught exactly such a mistake in this
+ * phase of development, where a more optimistic type cast did not.)
+ *
+ * An `instanceof` check is appropriate because the narrower type refines all of
+ * the following:
+ *
+ * - `valueType` is a subset of the full range of
+ *   {@link ValueType | specified value types} (only `int` or `decimal` are
+ *   supported for range controls)
+ *
+ * - addition of range-specific properties: `min`, `max`, `step`
+ */
+const assertRangeNodeDefinition: AssertRangeNodeDefinition = (definition) => {
+	if (definition instanceof RangeNodeDefinition) {
+		return;
+	}
+
+	/**
+	 * At time of writing we know there is no code path producing this
+	 * case, but appeasing the type checker for it now will guard against
+	 * it happening mistakenly in any future refactoring. (Hint: it
+	 * occurred during some refactoring that arrived here, which is why
+	 * this isn't a type cast!)
+	 */
+	throw new ErrorProductionDesignPendingError(
+		`Invalid <range> definition with value type: ${definition.valueType}`
+	);
 };
 
 const isTriggerNodeDefinition = (
@@ -127,20 +166,22 @@ export const buildChildren = (parent: GeneralParentNode): GeneralChildNode[] =>
 					return InputControl.from(parent, leafChild);
 				}
 
-				if (isSelectFieldDefinition(leafChild)) {
-					return new SelectField(parent, leafChild);
+				if (isSelectDefinition(leafChild)) {
+					return SelectControl.from(parent, leafChild);
 				}
 
-				if (isTriggerNodeDefinition(leafChild)) {
-					return new TriggerControl(parent, leafChild);
+				if (isRankDefinition(leafChild)) {
+					return RankControl.from(parent, leafChild);
 				}
 
-				if (isRangeNodeDefinition(leafChild)) {
-					return new RangeControl(parent, leafChild);
+				if (isTriggerNodeDefinition(leafChild)) {
+					return TriggerControl.from(parent, leafChild);
 				}
 
-				if (isRankNodeDefinition(leafChild)) {
-					return new RankControl(parent, leafChild);
+				if (isRangeLeafNodeDefinition(leafChild)) {
+					assertRangeNodeDefinition(leafChild);
+
+					return RangeControl.from(parent, leafChild);
 				}
 
 				if (isUploadNodeDefinition(leafChild)) {