@getodk/xforms-engine 0.5.0 → 0.7.0

package/src/instance/RangeControl.ts

@@ -0,0 +1,119 @@
+import { XPathNodeKindKey } from '@getodk/xpath';
+import type { Accessor } from 'solid-js';
+import type {
+	RangeInputValue,
+	RangeNode,
+	RangeNodeAppearances,
+	RangeValue,
+} from '../client/RangeNode.ts';
+import type { TextRange } from '../client/TextRange.ts';
+import type { XFormsXPathElement } from '../integration/xpath/adapter/XFormsXPathNode.ts';
+import type { StaticLeafElement } from '../integration/xpath/static-dom/StaticElement.ts';
+import { RangeCodec } from '../lib/codecs/RangeCodec.ts';
+import { getSharedValueCodec } from '../lib/codecs/getSharedValueCodec.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 {
+	AnyRangeNodeDefinition,
+	RangeNodeDefinition,
+	RangeValueType,
+} from '../parse/model/RangeNodeDefinition.ts';
+import type { Root } from './Root.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 { ClientReactiveSerializableValueNode } from './internal-api/serialization/ClientReactiveSerializableValueNode.ts';
+
+interface RangeControlStateSpec<V extends RangeValueType>
+	extends ValueNodeStateSpec<RangeValue<V>> {
+	readonly label: Accessor<TextRange<'label'> | null>;
+	readonly hint: Accessor<TextRange<'hint'> | null>;
+	readonly valueOptions: null;
+}
+
+export class RangeControl<V extends RangeValueType = RangeValueType>
+	extends ValueNode<V, RangeNodeDefinition<V>, RangeValue<V>, RangeInputValue<V>>
+	implements
+		RangeNode<V>,
+		XFormsXPathElement,
+		EvaluationContext,
+		ValidationContext,
+		ClientReactiveSerializableValueNode
+{
+	static from(
+		parent: GeneralParentNode,
+		instanceNode: StaticLeafElement | null,
+		definition: AnyRangeNodeDefinition
+	): AnyRangeControl;
+	static from<V extends RangeValueType>(
+		parent: GeneralParentNode,
+		instanceNode: StaticLeafElement | null,
+		definition: RangeNodeDefinition<V>
+	): RangeControl<V> {
+		return new this<V>(parent, instanceNode, definition);
+	}
+
+	// XFormsXPathElement
+	override readonly [XPathNodeKindKey] = 'element';
+
+	// InstanceNode
+	protected readonly state: SharedNodeState<RangeControlStateSpec<V>>;
+	protected readonly engineState: EngineState<RangeControlStateSpec<V>>;
+
+	// RangeNode
+	readonly nodeType = 'range';
+	readonly appearances: RangeNodeAppearances;
+	readonly nodeOptions = null;
+	readonly currentState: CurrentState<RangeControlStateSpec<V>>;
+
+	constructor(
+		parent: GeneralParentNode,
+		instanceNode: StaticLeafElement | null,
+		definition: RangeNodeDefinition<V>
+	) {
+		const baseCodec = getSharedValueCodec(definition.valueType);
+		const codec = new RangeCodec(baseCodec, definition);
+
+		super(parent, instanceNode, definition, codec);
+
+		this.appearances = definition.bodyElement.appearances;
+
+		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: null,
+				value: this.valueState,
+				instanceValue: this.getInstanceValue,
+			},
+			this.instanceConfig
+		);
+
+		this.state = state;
+		this.engineState = state.engineState;
+		this.currentState = state.currentState;
+	}
+
+	setValue(value: RangeInputValue<V>): Root {
+		this.setValueState(value);
+
+		return this.root;
+	}
+}
+
+// prettier-ignore
+export type AnyRangeControl =
+	| RangeControl<'decimal'>
+	| RangeControl<'int'>;

package/src/instance/RankControl.ts

@@ -0,0 +1,208 @@
+import { XPathNodeKindKey } from '@getodk/xpath';
+import type { Accessor } from 'solid-js';
+import { createMemo } from 'solid-js';
+import type { RankDefinition, RankItem, RankNode, RankValueOptions } from '../client/RankNode.ts';
+import type { TextRange } from '../client/TextRange.ts';
+import type { ValueType } from '../client/ValueType.ts';
+import { RankMissingValueError } from '../error/RankMissingValueError.ts';
+import { RankValueTypeError } from '../error/RankValueTypeError.ts';
+import type { XFormsXPathElement } from '../integration/xpath/adapter/XFormsXPathNode.ts';
+import type { StaticLeafElement } from '../integration/xpath/static-dom/StaticElement.ts';
+import { sharedValueCodecs } from '../lib/codecs/getSharedValueCodec.ts';
+import { MultipleValueItemCodec } from '../lib/codecs/items/MultipleValueItemCodec.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 { UnknownAppearanceDefinition } from '../parse/body/appearance/unknownAppearanceParser.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 { ClientReactiveSerializableValueNode } from './internal-api/serialization/ClientReactiveSerializableValueNode.ts';
+
+export type AnyRankDefinition = {
+	[V in ValueType]: RankDefinition<V>;
+}[ValueType];
+
+type AssertRankNodeDefinition = (
+	definition: AnyRankDefinition
+) => asserts definition is RankDefinition<'string'>;
+
+const assertRankNodeDefinition: AssertRankNodeDefinition = (definition) => {
+	if (definition.valueType !== 'string') {
+		throw new RankValueTypeError(definition);
+	}
+};
+
+type RankItemMap = ReadonlyMap<string, RankItem>;
+
+interface RankControlStateSpec extends ValueNodeStateSpec<readonly string[]> {
+	readonly label: Accessor<TextRange<'label'> | null>;
+	readonly hint: Accessor<TextRange<'hint'> | null>;
+	readonly valueOptions: Accessor<RankValueOptions>;
+}
+
+/**
+ * @ToDo We currently represent a blank value for `<odk:rank>` as an empty array.
+ * This is ambiguous, and likely to change.
+ *
+ * @see {@link https://github.com/getodk/web-forms/issues/295}
+ */
+type TempBlankValueState = readonly [];
+const isBlankValueState = (values: readonly string[]): values is TempBlankValueState => {
+	return values.length === 0;
+};
+
+export class RankControl
+	extends ValueNode<'string', RankDefinition<'string'>, readonly string[], readonly string[]>
+	implements
+		RankNode,
+		XFormsXPathElement,
+		EvaluationContext,
+		ValidationContext,
+		ClientReactiveSerializableValueNode
+{
+	static from(
+		parent: GeneralParentNode,
+		instanceNode: StaticLeafElement | null,
+		definition: RankDefinition
+	): RankControl;
+	static from(
+		parent: GeneralParentNode,
+		instanceNode: StaticLeafElement | null,
+		definition: AnyRankDefinition
+	): RankControl {
+		assertRankNodeDefinition(definition);
+		return new this(parent, instanceNode, definition);
+	}
+
+	private readonly mapOptionsByValue: Accessor<RankItemMap>;
+
+	protected override readonly getInstanceValue: Accessor<string>;
+
+	// XFormsXPathElement
+	override readonly [XPathNodeKindKey] = 'element';
+
+	// InstanceNode
+	protected readonly state: SharedNodeState<RankControlStateSpec>;
+	protected readonly engineState: EngineState<RankControlStateSpec>;
+
+	// RankNode
+	readonly nodeType = 'rank';
+	readonly appearances: UnknownAppearanceDefinition;
+	readonly nodeOptions = null;
+	readonly currentState: CurrentState<RankControlStateSpec>;
+
+	private constructor(
+		parent: GeneralParentNode,
+		instanceNode: StaticLeafElement | null,
+		definition: RankDefinition<'string'>
+	) {
+		const codec = new MultipleValueItemCodec(sharedValueCodecs.string);
+		super(parent, instanceNode, definition, codec);
+
+		this.appearances = definition.bodyElement.appearances;
+
+		const valueOptions = createItemCollection(this);
+		const mapOptionsByValue: Accessor<RankItemMap> = 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;
+
+		/**
+		 * @ToDo As new value options become available, they're not yet in the
+		 * `currentValues` state. This appends them. We intend to change this
+		 * behavior, likely clearing the previous state instead.
+		 *
+		 * However, there's an open question about what we should do when a filter
+		 * change **only removes values**.
+		 */
+		const getValue = this.scope.runTask(() => {
+			return createMemo(() => {
+				const options = valueOptions();
+				const values = baseGetValue();
+
+				if (isBlankValueState(values)) {
+					return values;
+				}
+
+				const optionValues = new Set(options.map((option) => option.value));
+
+				/**
+				 * @see {@link getValue} ToDo paragraph 2.
+				 */
+				const currentValues = values.filter((value) => optionValues.has(value));
+
+				return Array.from(
+					new Set([
+						...currentValues,
+						/**
+						 * @see {@link getValue} ToDo paragraph 1.
+						 */
+						...optionValues,
+					])
+				);
+			});
+		});
+		const valueState: SimpleAtomicState<readonly string[]> = [getValue, setValue];
+
+		this.getInstanceValue = this.scope.runTask(() => {
+			return createMemo(() => codec.encodeValue(getValue()));
+		});
+
+		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,
+			},
+			this.instanceConfig
+		);
+
+		this.state = state;
+		this.engineState = state.engineState;
+		this.currentState = state.currentState;
+	}
+
+	getValueLabel(value: string): TextRange<'item-label'> | null {
+		const valueOption = this.currentState.valueOptions.find((item) => item.value === value);
+		return valueOption?.label ?? null;
+	}
+
+	setValues(valuesInOrder: readonly string[]): Root {
+		if (isBlankValueState(valuesInOrder)) {
+			this.setValueState(valuesInOrder);
+			return this.root;
+		}
+
+		const sourceValues: string[] = Array.from(this.mapOptionsByValue().keys());
+		const hasAllValues = sourceValues.every((sourceValue) => valuesInOrder.includes(sourceValue));
+		if (!hasAllValues) {
+			throw new RankMissingValueError('There are missing options. Rank should have all options.');
+		}
+
+		this.setValueState(valuesInOrder);
+		return this.root;
+	}
+}

package/src/instance/Root.ts

@@ -3,16 +3,15 @@ import type { Accessor } from 'solid-js';
 import type { ActiveLanguage, FormLanguage, FormLanguages } from '../client/FormLanguage.ts';
 import type { FormNodeID } from '../client/identity.ts';
 import type { RootNode } from '../client/RootNode.ts';
-import type { SubmissionDefinition } from '../client/submission/SubmissionDefinition.ts';
+import type { InstancePayload } from '../client/serialization/InstancePayload.ts';
 import type {
-	SubmissionChunkedType,
-	SubmissionOptions,
-} from '../client/submission/SubmissionOptions.ts';
-import type { SubmissionResult } from '../client/submission/SubmissionResult.ts';
-import type { SubmissionState } from '../client/submission/SubmissionState.ts';
+	InstancePayloadOptions,
+	InstancePayloadType,
+} from '../client/serialization/InstancePayloadOptions.ts';
+import type { InstanceState } from '../client/serialization/InstanceState.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 { createRootInstanceState } from '../lib/client-reactivity/instance-state/createRootInstanceState.ts';
 import type { ChildrenState } from '../lib/reactivity/createChildrenState.ts';
 import { createChildrenState } from '../lib/reactivity/createChildrenState.ts';
 import type { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
@@ -25,10 +24,10 @@ import { createAggregatedViolations } from '../lib/reactivity/validation/createA
 import type { BodyClassList } from '../parse/body/BodyDefinition.ts';
 import type { RootDefinition } from '../parse/model/RootDefinition.ts';
 import { DescendantNode } from './abstract/DescendantNode.ts';
-import { buildChildren } from './children.ts';
+import { buildChildren } from './children/buildChildren.ts';
 import type { GeneralChildNode } from './hierarchy.ts';
 import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
-import type { ClientReactiveSubmittableParentNode } from './internal-api/submission/ClientReactiveSubmittableParentNode.ts';
+import type { ClientReactiveSerializableParentNode } from './internal-api/serialization/ClientReactiveSerializableParentNode.ts';
 import type { TranslationContext } from './internal-api/TranslationContext.ts';
 import type { PrimaryInstance } from './PrimaryInstance.ts';
 
@@ -54,7 +53,7 @@ export class Root
 		XFormsXPathElement,
 		EvaluationContext,
 		TranslationContext,
-		ClientReactiveSubmittableParentNode<GeneralChildNode>
+		ClientReactiveSerializableParentNode<GeneralChildNode>
 {
 	private readonly childrenState: ChildrenState<GeneralChildNode>;
 
@@ -76,25 +75,20 @@ 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;
-	readonly submissionState: SubmissionState;
-
-	// ClientReactiveSubmittableInstance
-	get submissionDefinition(): SubmissionDefinition {
-		return this.definition.submission;
-	}
-
-	// RootNode
+	readonly instanceState: InstanceState;
 	readonly languages: FormLanguages;
 
 	constructor(parent: PrimaryInstance) {
-		const { definition } = parent;
+		const { definition, instanceNode: instance } = parent;
+		const instanceNode = instance.root;
 		const { nodeset: reference } = definition;
 		const computeReference: Accessor<string> = () => reference;
 
-		super(parent, definition, {
+		super(parent, instanceNode, definition, {
 			computeReference,
 		});
 
@@ -105,10 +99,6 @@ export class Root
 		this.childrenState = childrenState;
 		this.languages = parent.languages;
 
-		const sharedStateOptions = {
-			clientStateFactory: this.engineConfig.stateFactory,
-		};
-
 		const state = createSharedNodeState(
 			this.scope,
 			{
@@ -123,7 +113,7 @@ export class Root
 				value: null,
 				children: childrenState.childIds,
 			},
-			sharedStateOptions
+			this.instanceConfig
 		);
 
 		this.state = state;
@@ -135,8 +125,8 @@ export class Root
 		);
 
 		childrenState.setChildren(buildChildren(this));
-		this.validationState = createAggregatedViolations(this, sharedStateOptions);
-		this.submissionState = createParentNodeSubmissionState(this);
+		this.validationState = createAggregatedViolations(this, this.instanceConfig);
+		this.instanceState = createRootInstanceState(this);
 	}
 
 	getChildren(): readonly GeneralChildNode[] {
@@ -150,9 +140,9 @@ export class Root
 		return this;
 	}
 
-	prepareSubmission<ChunkedType extends SubmissionChunkedType = 'monolithic'>(
-		options?: SubmissionOptions<ChunkedType>
-	): Promise<SubmissionResult<ChunkedType>> {
-		return this.rootDocument.prepareSubmission(options);
+	prepareInstancePayload<PayloadType extends InstancePayloadType = 'monolithic'>(
+		options?: InstancePayloadOptions<PayloadType>
+	): Promise<InstancePayload<PayloadType>> {
+		return this.rootDocument.prepareInstancePayload(options);
 	}
 }

package/src/instance/SelectControl.ts

@@ -0,0 +1,228 @@
+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 type { StaticLeafElement } from '../integration/xpath/static-dom/StaticElement.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 { ClientReactiveSerializableValueNode } from './internal-api/serialization/ClientReactiveSerializableValueNode.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,
+		ClientReactiveSerializableValueNode
+{
+	static from(
+		parent: GeneralParentNode,
+		instanceNode: StaticLeafElement | null,
+		definition: SelectDefinition
+	): SelectControl;
+	static from(
+		parent: GeneralParentNode,
+		instanceNode: StaticLeafElement | null,
+		definition: AnySelectDefinition
+	): SelectControl {
+		assertSupportedSelectValueType(definition);
+
+		return new this(parent, instanceNode, 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,
+		instanceNode: StaticLeafElement | null,
+		definition: SelectDefinition<'string'>
+	) {
+		const codec = getSelectCodec(definition);
+
+		super(parent, instanceNode, 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 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,
+			},
+			this.instanceConfig
+		);
+
+		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;
+	}
+}