@getodk/xforms-engine 0.5.0 → 0.6.0

package/src/error/RankValueTypeError.ts

@@ -0,0 +1,13 @@
+import { XFormsSpecViolationError } from './XFormsSpecViolationError.ts';
+import type { RankDefinition } from '../client/RankNode.ts';
+import type { UnsupportedBaseItemValueType } from '../lib/codecs/items/BaseItemCodec.ts';
+
+export class RankValueTypeError extends XFormsSpecViolationError {
+	constructor(definition: RankDefinition<UnsupportedBaseItemValueType>) {
+		const { valueType } = definition;
+
+		super(
+			`Ranks of type ${valueType} are not currently supported. If this functionality would be useful for your form, your feedback is welcome!`
+		);
+	}
+}

package/src/error/SelectValueTypeError.ts

@@ -0,0 +1,22 @@
+import type { SelectDefinition } from '../client/SelectNode.ts';
+import type { UnsupportedBaseItemValueType } from '../lib/codecs/items/BaseItemCodec.ts';
+import { XFormsSpecViolationError } from './XFormsSpecViolationError.ts';
+
+/**
+ * @todo It would be good to have a standardized way to use specific types of
+ * errors as a prompt for feedback. There is currently a feedback link presented
+ * by `@getodk/web-forms`, which is conditionally displayed (condition is
+ * evidently controlled by a
+ * {@link https://vuejs.org/api/sfc-script-setup#defineoptions | Vue component option}).
+ *
+ * @see {@link https://github.com/getodk/web-forms/issues/276}
+ */
+export class SelectValueTypeError extends XFormsSpecViolationError {
+	constructor(definition: SelectDefinition<UnsupportedBaseItemValueType>) {
+		const { valueType } = definition;
+
+		super(
+			`Selects of type ${valueType} are not currently supported. If this functionality would be useful for your form, your feedback is welcome!`
+		);
+	}
+}

package/src/error/XFormsSpecViolationError.ts

@@ -0,0 +1 @@
+export abstract class XFormsSpecViolationError extends Error {}

package/src/index.ts

@@ -24,6 +24,7 @@ export type * from './client/InputNode.ts';
 export type * from './client/ModelValueNode.ts';
 export type * from './client/NoteNode.ts';
 export type * from './client/OpaqueReactiveObjectFactory.ts';
+export type * from './client/RangeNode.ts';
 export type * from './client/repeat/RepeatInstanceNode.ts';
 export type * from './client/repeat/RepeatRangeControlledNode.ts';
 export type * from './client/repeat/RepeatRangeUncontrolledNode.ts';
@@ -39,18 +40,7 @@ export type * from './client/submission/SubmissionState.ts';
 export type * from './client/SubtreeNode.ts';
 export type * from './client/TextRange.ts';
 export type * from './client/TriggerNode.ts';
-export type * from './client/unsupported/RangeNode.ts';
-export type * from './client/unsupported/RankNode.ts';
+export type * from './client/RankNode.ts';
 export type * from './client/unsupported/UploadNode.ts';
 export type * from './client/validation.ts';
 export type * from './client/ValueType.ts';
-
-// TODO: notwithstanding potential conflicts with parallel work on `web-forms`
-// (former `ui-vue`), these are the last remaining references **outside of
-// `xforms-engine`** to anything besides /client/* and the `initializeForm`
-// entrypoint implementation. We'll refine the various `definition` types in due
-// time.
-export type {
-	AnySelectDefinition,
-	SelectDefinition,
-} from './parse/body/control/select/SelectDefinition.ts';

package/src/instance/Group.ts

@@ -52,6 +52,7 @@ export class Group
 	// GroupNode
 	readonly nodeType = 'group';
 	readonly appearances: GroupNodeAppearances;
+	readonly nodeOptions = null;
 	readonly currentState: MaterializedChildren<CurrentState<GroupStateSpec>, GeneralChildNode>;
 	readonly validationState: AncestorNodeValidationState;
 	readonly submissionState: SubmissionState;

package/src/instance/InputControl.ts

@@ -5,6 +5,7 @@ import type {
 	InputNode,
 	InputNodeAppearances,
 	InputNodeInputValue,
+	InputNodeOptions,
 } from '../client/InputNode.ts';
 import type { TextRange } from '../client/TextRange.ts';
 import type { ValueType } from '../client/ValueType.ts';
@@ -17,20 +18,57 @@ import type { SharedNodeState } from '../lib/reactivity/node-state/createSharedN
 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 { Root } from './Root.ts';
+import type { InputControlDefinition } from '../parse/body/control/InputControlDefinition.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 { ClientReactiveSubmittableValueNode } from './internal-api/submission/ClientReactiveSubmittableValueNode.ts';
+import type { ValidationContext } from './internal-api/ValidationContext.ts';
+import type { Root } from './Root.ts';
 
 export type AnyInputDefinition = {
 	[V in ValueType]: InputDefinition<V>;
 }[ValueType];
 
+const stringInputNodeOptions = (control: InputControlDefinition): InputNodeOptions<'string'> => ({
+	rows: control.rows,
+});
+
+const geoInputNodeOptions = (
+	control: InputControlDefinition
+): InputNodeOptions<'geopoint' | 'geoshape' | 'geotrace'> => ({
+	accuracyThreshold: control.accuracyThreshold,
+	unacceptableAccuracyThreshold: control.unacceptableAccuracyThreshold,
+});
+
+type NodeOptionsFactory<V extends ValueType> = (
+	controlDefinition: InputControlDefinition
+) => InputNodeOptions<V>;
+
+type NodeOptionsFactoryByType = {
+	[V in ValueType]: NodeOptionsFactory<V>;
+};
+
+const nodeOptionsFactoryByType: NodeOptionsFactoryByType = {
+	string: stringInputNodeOptions,
+	int: () => null,
+	boolean: () => null,
+	decimal: () => null,
+	date: () => null,
+	time: () => null,
+	dateTime: () => null,
+	geopoint: geoInputNodeOptions,
+	geotrace: geoInputNodeOptions,
+	geoshape: geoInputNodeOptions,
+	binary: () => null,
+	barcode: () => null,
+	intent: () => null,
+};
+
 interface InputControlStateSpec<V extends ValueType> extends ValueNodeStateSpec<RuntimeValue<V>> {
 	readonly label: Accessor<TextRange<'label'> | null>;
 	readonly hint: Accessor<TextRange<'hint'> | null>;
+	readonly valueOptions: null;
 }
 
 export class InputControl<V extends ValueType = ValueType>
@@ -60,6 +98,7 @@ export class InputControl<V extends ValueType = ValueType>
 	// InputNode
 	readonly nodeType = 'input';
 	readonly appearances: InputNodeAppearances;
+	readonly nodeOptions: InputNodeOptions<V>;
 	readonly currentState: CurrentState<InputControlStateSpec<V>>;
 
 	constructor(parent: GeneralParentNode, definition: InputDefinition<V>) {
@@ -68,6 +107,7 @@ export class InputControl<V extends ValueType = ValueType>
 		super(parent, definition, codec);
 
 		this.appearances = definition.bodyElement.appearances;
+		this.nodeOptions = nodeOptionsFactoryByType[definition.valueType](definition.bodyElement);
 
 		const sharedStateOptions = {
 			clientStateFactory: this.engineConfig.stateFactory,

package/src/instance/ModelValue.ts

@@ -17,6 +17,7 @@ import type { ClientReactiveSubmittableValueNode } from './internal-api/submissi
 interface ModelValueStateSpec<V extends ValueType> extends ValueNodeStateSpec<RuntimeValue<V>> {
 	readonly label: null;
 	readonly hint: null;
+	readonly valueOptions: null;
 }
 
 export class ModelValue<V extends ValueType = ValueType>
@@ -46,6 +47,7 @@ export class ModelValue<V extends ValueType = ValueType>
 	// ModelValueNode
 	readonly nodeType = 'model-value';
 	readonly appearances = null;
+	readonly nodeOptions = null;
 	readonly currentState: CurrentState<ModelValueStateSpec<V>>;
 
 	constructor(parent: GeneralParentNode, definition: ModelValueDefinition<V>) {

package/src/instance/Note.ts

@@ -1,15 +1,13 @@
 import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
-import { identity } from '@getodk/common/lib/identity.ts';
 import { XPathNodeKindKey } from '@getodk/xpath';
 import type { Accessor } from 'solid-js';
-import type { NoteNode, NoteNodeAppearances } from '../client/NoteNode.ts';
-import type { SubmissionState } from '../client/submission/SubmissionState.ts';
+import type { NoteNode, NoteNodeAppearances, NoteValue } from '../client/NoteNode.ts';
 import type { TextRange } from '../client/TextRange.ts';
-import type { AnyViolation, LeafNodeValidationState } from '../client/validation.ts';
+import type { ValueType } from '../client/ValueType.ts';
 import type { XFormsXPathElement } from '../integration/xpath/adapter/XFormsXPathNode.ts';
-import { createLeafNodeSubmissionState } from '../lib/client-reactivity/submission/createLeafNodeSubmissionState.ts';
+import { getNoteCodec } from '../lib/codecs/getNoteCodec.ts';
+import type { NoteInputValue, NoteRuntimeValue } from '../lib/codecs/NoteCodec.ts';
 import { createNoteReadonlyThunk } from '../lib/reactivity/createNoteReadonlyThunk.ts';
-import { createValueState } from '../lib/reactivity/createValueState.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';
@@ -17,65 +15,47 @@ import { createSharedNodeState } from '../lib/reactivity/node-state/createShared
 import { createFieldHint } from '../lib/reactivity/text/createFieldHint.ts';
 import { createNodeLabel } from '../lib/reactivity/text/createNodeLabel.ts';
 import { createNoteText, type ComputedNoteText } from '../lib/reactivity/text/createNoteText.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 { NoteNodeDefinition } from '../parse/model/NoteNodeDefinition.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 { ClientReactiveSubmittableLeafNode } from './internal-api/submission/ClientReactiveSubmittableLeafNode.ts';
+import type { ClientReactiveSubmittableValueNode } from './internal-api/submission/ClientReactiveSubmittableValueNode.ts';
 import type { ValidationContext } from './internal-api/ValidationContext.ts';
-import type { ValueContext } from './internal-api/ValueContext.ts';
 
-interface NoteStateSpec extends DescendantNodeStateSpec<string> {
+interface NoteStateSpec<V extends ValueType> extends ValueNodeStateSpec<NoteValue<V>> {
 	readonly readonly: Accessor<true>;
 	readonly noteText: ComputedNoteText;
 	readonly label: Accessor<TextRange<'label', 'form'> | null>;
 	readonly hint: Accessor<TextRange<'hint', 'form'> | null>;
-	readonly children: null;
-	readonly value: SimpleAtomicState<string>;
 	readonly valueOptions: null;
 }
 
-export class Note
-	extends DescendantNode<NoteNodeDefinition, NoteStateSpec, GeneralParentNode, null>
+export class Note<V extends ValueType = ValueType>
+	extends ValueNode<V, NoteNodeDefinition<V>, NoteRuntimeValue<V>, NoteInputValue<V>>
 	implements
 		NoteNode,
 		XFormsXPathElement,
 		EvaluationContext,
 		ValidationContext,
-		ValueContext<string>,
-		ClientReactiveSubmittableLeafNode<string>
+		ClientReactiveSubmittableValueNode
 {
-	private readonly validation: SharedValidationState;
-
 	// XFormsXPathElement
 	override readonly [XPathNodeKindKey] = 'element';
 
 	// InstanceNode
-	protected readonly state: SharedNodeState<NoteStateSpec>;
-	protected readonly engineState: EngineState<NoteStateSpec>;
+	protected readonly state: SharedNodeState<NoteStateSpec<V>>;
+	protected readonly engineState: EngineState<NoteStateSpec<V>>;
 
 	// NoteNode
 	readonly nodeType = 'note';
 	readonly appearances: NoteNodeAppearances;
-	readonly currentState: CurrentState<NoteStateSpec>;
-
-	get validationState(): LeafNodeValidationState {
-		return this.validation.currentState;
-	}
-
-	readonly submissionState: SubmissionState;
+	readonly nodeOptions = null;
+	readonly currentState: CurrentState<NoteStateSpec<V>>;
 
-	// ValueContext
-	override readonly contextNode = this;
-	readonly encodeValue = identity<string>;
-	readonly decodeValue = identity<string>;
+	constructor(parent: GeneralParentNode, definition: NoteNodeDefinition<V>) {
+		const codec = getNoteCodec(definition.valueType);
 
-	constructor(parent: GeneralParentNode, definition: NoteNodeDefinition) {
-		super(parent, definition);
+		super(parent, definition, codec);
 
 		this.appearances = definition.bodyElement.appearances;
 
@@ -125,7 +105,8 @@ export class Note
 
 				children: null,
 				valueOptions: null,
-				value: createValueState(this),
+				value: this.valueState,
+				instanceValue: this.getInstanceValue,
 			},
 			sharedStateOptions
 		);
@@ -133,26 +114,20 @@ export class Note
 		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.engineState.value;
-	}
-
-	// ValidationContext
-	getViolation(): AnyViolation | null {
-		return this.validation.engineState.violation;
-	}
-
-	isBlank(): boolean {
-		return this.engineState.value === '';
-	}
-
-	// InstanceNode
-	getChildren(): readonly [] {
-		return [];
 	}
 }
+
+export type AnyNote =
+	| Note<'barcode'>
+	| Note<'binary'>
+	| Note<'boolean'>
+	| Note<'date'>
+	| Note<'dateTime'>
+	| Note<'decimal'>
+	| Note<'geopoint'>
+	| Note<'geoshape'>
+	| Note<'geotrace'>
+	| Note<'int'>
+	| Note<'intent'>
+	| Note<'string'>
+	| Note<'time'>;

package/src/instance/PrimaryInstance.ts

@@ -102,6 +102,7 @@ export class PrimaryInstance
 	// PrimaryInstanceDocument, ClientReactiveSubmittableInstance
 	readonly nodeType = 'primary-instance';
 	readonly appearances = null;
+	readonly nodeOptions = null;
 	readonly classes: BodyClassList;
 	readonly root: Root;
 	readonly currentState: MaterializedChildren<CurrentState<PrimaryInstanceStateSpec>, Root>;

package/src/instance/RangeControl.ts

@@ -0,0 +1,113 @@
+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 { 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 { ClientReactiveSubmittableValueNode } from './internal-api/submission/ClientReactiveSubmittableValueNode.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,
+		ClientReactiveSubmittableValueNode
+{
+	static from(parent: GeneralParentNode, definition: AnyRangeNodeDefinition): AnyRangeControl;
+	static from<V extends RangeValueType>(
+		parent: GeneralParentNode,
+		definition: RangeNodeDefinition<V>
+	): RangeControl<V> {
+		return new this<V>(parent, 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, definition: RangeNodeDefinition<V>) {
+		const baseCodec = getSharedValueCodec(definition.valueType);
+		const codec = new RangeCodec(baseCodec, definition);
+
+		super(parent, definition, codec);
+
+		this.appearances = definition.bodyElement.appearances;
+
+		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: null,
+				value: this.valueState,
+				instanceValue: this.getInstanceValue,
+			},
+			sharedStateOptions
+		);
+
+		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,199 @@
+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 { XFormsXPathElement } from '../integration/xpath/adapter/XFormsXPathNode.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 { 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';
+import { MultipleValueItemCodec } from '../lib/codecs/items/MultipleValueItemCodec.ts';
+import { sharedValueCodecs } from '../lib/codecs/getSharedValueCodec.ts';
+import { createItemCollection } from '../lib/reactivity/createItemCollection.ts';
+import type { UnknownAppearanceDefinition } from '../parse/body/appearance/unknownAppearanceParser.ts';
+import type { ValueType } from '../client/ValueType.ts';
+import { RankMissingValueError } from '../error/RankMissingValueError.ts';
+import { RankValueTypeError } from '../error/RankValueTypeError.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,
+		ClientReactiveSubmittableValueNode
+{
+	static from(parent: GeneralParentNode, definition: RankDefinition): RankControl;
+	static from(parent: GeneralParentNode, definition: AnyRankDefinition): RankControl {
+		assertRankNodeDefinition(definition);
+		return new this(parent, 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, definition: RankDefinition<'string'>) {
+		const codec = new MultipleValueItemCodec(sharedValueCodecs.string);
+		super(parent, 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 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;
+	}
+
+	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;
+	}
+}