@getodk/xforms-engine 0.4.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getodk/xforms-engine",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "license": "Apache-2.0",
   "description": "XForms engine for ODK Web Forms",
   "type": "module",
@@ -29,7 +29,7 @@
     "README.md"
   ],
   "engines": {
-    "node": "^18.20.4 || ^20.17.0 || ^22.8.0",
+    "node": "^18.20.5 || ^20.18.1 || ^22.12.0",
     "yarn": "1.22.22"
   },
   "scripts": {
@@ -54,29 +54,34 @@
     "test:types": "tsc --project ./tsconfig.json --emitDeclarationOnly false --noEmit"
   },
   "dependencies": {
-    "solid-js": "^1.8.22"
+    "papaparse": "^5.4.1",
+    "solid-js": "^1.9.3"
   },
   "devDependencies": {
-    "@babel/core": "^7.25.2",
+    "@babel/core": "^7.26.0",
     "@getodk/tree-sitter-xpath": "0.1.2",
-    "@getodk/xpath": "0.2.0",
-    "@playwright/test": "^1.46.1",
-    "@vitest/browser": "^2.0.5",
+    "@getodk/xpath": "0.4.0",
+    "@playwright/test": "^1.49.1",
+    "@types/papaparse": "^5.3.15",
+    "@vitest/browser": "^2.1.8",
     "babel-plugin-transform-jsbi-to-bigint": "^1.4.0",
     "http-server": "^14.1.1",
-    "jsdom": "^25.0.0",
-    "typedoc": "^0.26.6",
-    "vite": "^5.4.3",
-    "vite-plugin-dts": "^4.1.0",
+    "jsdom": "^25.0.1",
+    "typedoc": "^0.27.5",
+    "vite": "^5.4.11",
+    "vite-plugin-dts": "^4.3.0",
     "vite-plugin-no-bundle": "^4.0.0",
-    "vitest": "^2.0.5"
+    "vitest": "^2.1.8"
   },
   "peerDependencies": {
-    "solid-js": "^1.8.18"
+    "solid-js": "^1.9.3"
   },
   "peerDependenciesMeta": {
     "solid-js": {
       "optional": true
     }
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/src/client/BaseNode.ts

@@ -3,7 +3,9 @@ import type { AnyNodeDefinition } from '../parse/model/NodeDefinition.ts';
 import type { NodeAppearances } from './NodeAppearances.ts';
 import type { OpaqueReactiveObjectFactory } from './OpaqueReactiveObjectFactory.ts';
 import type { TextRange } from './TextRange.ts';
+import type { FormNodeID } from './identity.ts';
 import type { InstanceNodeType } from './node-types.ts';
+import type { SubmissionState } from './submission/SubmissionState.ts';
 import type {
 	AncestorNodeValidationState,
 	LeafNodeValidationState,
@@ -129,8 +131,6 @@ export interface BaseNodeState {
 	get value(): unknown;
 }
 
-type FormNodeID = string;
-
 /**
  * Base interface for common/shared aspects of any node type.
  */
@@ -153,6 +153,11 @@ export interface BaseNode {
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	readonly appearances: NodeAppearances<any> | null;
 
+	/**
+	 * A node can have options that determine its behavior.
+	 */
+	readonly nodeOptions: object | null;
+
 	/**
 	 * Each node has a definition which specifies aspects of the node defined in
 	 * the form. These aspects include (but are not limited to) the node's data
@@ -189,15 +194,13 @@ export interface BaseNode {
 	// 2. If `parent` does become nullable state, how best to convey the same
 	//    information for removed descendants. Some ideas:
 	//
-	//    - Apply null-as-removed recursively. This wouldn't technically be true
-	//      for the engine's current use of a DOM backing store (but that's an
-	//      implementation detail clients don't/shouldn't care about).
+	//    - Apply null-as-removed recursively.
 	//
 	//    - Borrow the browser DOM's notion of node "connected"-ness. When a node
 	//      is removed, its `isConnected` property is `false`. The same is true
 	//      for any of its descendants, even though they retain their own direct
 	//      parent reference.
-	readonly parent: BaseNode | null;
+	readonly parent: unknown;
 
 	/**
 	 * Each node provides a discrete object representing the stateful aspects\* of
@@ -251,4 +254,16 @@ export interface BaseNode {
 	 * clients to explicitly pause and resume recomputation.
 	 */
 	readonly validationState: NodeValidationState;
+
+	/**
+	 * Represents the current submission state of the node.
+	 *
+	 * @see {@link SubmissionState.submissionXML} for additional detail.
+	 *
+	 * @todo Consider whether this can (should) be merged with
+	 * {@link currentState}, while providing the same client-reactivity
+	 * guarantees. (The challenge there is in defining client-reactive state which
+	 * self-referentially derives state from its own definition.)
+	 */
+	readonly submissionState: SubmissionState;
 }

package/src/client/BaseValueNode.ts

@@ -0,0 +1,35 @@
+import type { LeafNodeDefinition } from '../parse/model/LeafNodeDefinition.ts';
+import type { BaseNode, BaseNodeState } from './BaseNode.ts';
+import type { GeneralParentNode } from './hierarchy.ts';
+import type { LeafNodeType } from './node-types.ts';
+import type { LeafNodeValidationState } from './validation.ts';
+import type { ValueType } from './ValueType.ts';
+
+export interface BaseValueNodeState<Value> extends BaseNodeState {
+	get children(): null;
+	get valueOptions(): unknown;
+	get value(): Value;
+
+	/**
+	 * Reflects the serialized string representation of a {@link BaseValueNode}'s
+	 * {@link value} state. This representation allows access to the node's value
+	 * _as primary instance state_. In other words, this is the value which:
+	 *
+	 * - would be serialized as a text node in
+	 *   {@link SubmissionState.submissionXML} (note: this value is **NOT**
+	 *   escaped for XML serialization, as it is there)
+	 *
+	 * - is used when the node's value is referenced in any of a form's XPath
+	 *   expressions
+	 */
+	get instanceValue(): string;
+}
+
+export interface BaseValueNode<V extends ValueType = ValueType, Value = string> extends BaseNode {
+	readonly nodeType: LeafNodeType;
+	readonly valueType: V;
+	readonly definition: LeafNodeDefinition;
+	readonly parent: GeneralParentNode;
+	readonly currentState: BaseValueNodeState<Value>;
+	readonly validationState: LeafNodeValidationState;
+}

package/src/client/EngineConfig.ts

@@ -1,35 +1,7 @@
+import type { initializeForm } from '../instance/index.ts';
+import type { MissingResourceBehavior, MissingResourceBehaviorDefault } from './constants.ts';
 import type { OpaqueReactiveObjectFactory } from './OpaqueReactiveObjectFactory.ts';
-
-/**
- * @todo this is currently a strict subset of the web standard `Response`. Is it
- * sufficient? Ways it might not be:
- *
- * - No way to convey metadata about the resource
- * - Ambiguous if a client supplies an alternative implementation which doesn't
- *   exhaust the body on access
- */
-export interface FetchResourceResponse {
-	readonly ok?: boolean;
-	readonly body?: ReadableStream<Uint8Array> | null;
-	readonly bodyUsed?: boolean;
-
-	readonly blob: () => Promise<Blob>;
-	readonly text: () => Promise<string>;
-}
-
-/**
- * @todo this is a strict subset of the web standard `fetch` interface. It
- * implicitly assumes that the engine itself will only ever issue `GET`-like
- * requests. It also provides no further request-like semantics to the engine.
- * This is presumed sufficient for now, but notably doesn't expose any notion of
- * content negotiation (e.g. the ability to supply `Accept` headers).
- *
- * This also completely ignores any notion of mapping
- * {@link https://getodk.github.io/xforms-spec/#uris | `jr:` URLs} to their
- * actual resources (likely, but not necessarily, accessed at a corresponding
- * HTTP URL).
- */
-export type FetchResource = (resource: URL) => Promise<FetchResourceResponse>;
+import type { FetchFormAttachment, FetchResource } from './resources.ts';
 
 /**
  * Options provided by a client to specify certain aspects of engine runtime
@@ -55,29 +27,58 @@ export interface EngineConfig {
 	readonly stateFactory?: OpaqueReactiveObjectFactory;
 
 	/**
-	 * A client may specify a generic function for retrieving resources referenced
-	 * by a form, such as:
 	 *
-	 * - Form definitions themselves (if not provided directly to the engine by
-	 *   the client)
-	 * - External secondary instances
-	 * - Media (images, audio, video, etc.)
+	 * A client may specify an arbitrary {@link fetch}-like function for retrieving an XML XForm form
+	 * definition.
+	 *
+	 * Notes:
+	 *
+	 * - This configuration will only be consuled for calls to
+	 *   {@link initializeForm} with a URL referencing an XML XForm definition. It
+	 *   will be ignored for calls passing an XML XForm form definition directly.
+	 *
+	 * - For calls to {@link initializeForm} with a URL, if this configuration is
+	 *   not specified it will default to the global {@link fetch} function (if
+	 *   one is defined).
+	 */
+	readonly fetchFormDefinition?: FetchResource;
+
+	/**
+	 * A client may specify an arbitrary {@link fetch}-like function to retrieve a
+	 * form's attachments, i.e. any `jr:` URL referenced by the form (as specified
+	 * by {@link https://getodk.github.io/xforms-spec/ | ODK XForms}).
+	 *
+	 * Notes:
 	 *
-	 * The function is expected to be a subset of the
-	 * {@link https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API | Fetch API},
-	 * performing `GET` requests for:
+	 * - This configuration will be consulted for all supported form attachments,
+	 *   as a part of {@link initializeForm | form initialization}.
 	 *
-	 * - Text resources (e.g. XML, CSV, JSON/GeoJSON)
-	 * - Binary resources (e.g. media)
-	 * - Optionally streamed binary data of either (e.g. for optimized
-	 *   presentation of audio/video)
+	 * - If this configuration is not specified it will default to the global
+	 *   {@link fetch} function (if one is defined).
+	 *
+	 * This default behavior will typically result in failure to load form
+	 * attachments—and in most cases this will also cause
+	 * {@link initializeForm | form initialization} to fail overall—with the
+	 * following exceptions:
+	 *
+	 * - **CLIENT-SPECIFIC:** Usage in coordination with a client-implemented
+	 *   {@link https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API | Serivce Worker},
+	 *   which can intercept network requests **generally**. Clients already using
+	 *   a Service Worker may opt for the convenience of handling network requests
+	 *   for `jr:` URLs along with any other network interception logic. Client
+	 *   implementors should be warned, however, that such `jr:` URLs are not
+	 *   namespaced or otherwise scoped to a particular form; such a client would
+	 *   therefore inherently need to coordinate state between the Service Worker
+	 *   and the main thread (or whatever other realm calls
+	 *   {@link initializeForm}).
+	 */
+	readonly fetchFormAttachment?: FetchFormAttachment;
+
+	/**
+	 * @see {@link MissingResourceBehavior}
+	 * @see {@link MissingResourceBehaviorDefault}
 	 *
-	 * If provided by a client, this function will be used by the engine to
-	 * retrieve any such resource, as required for engine functionality. If
-	 * absent, the engine will use the native `fetch` function (if available, a
-	 * polyfill otherwise). Clients may use this function to provide resources
-	 * from sources other than the network, (or even in a test client to provide
-	 * e.g. resources from test fixtures).
+	 * @default MissingResourceBehaviorDefault
 	 */
-	readonly fetchResource?: FetchResource;
+	readonly missingResourceBehavior?: MissingResourceBehavior;
 }

package/src/client/GroupNode.ts

@@ -31,6 +31,7 @@ export type GroupNodeAppearances = NodeAppearances<GroupDefinition>;
 export interface GroupNode extends BaseNode {
 	readonly nodeType: 'group';
 	readonly appearances: GroupNodeAppearances;
+	readonly nodeOptions: null;
 	readonly definition: GroupDefinition;
 	readonly root: RootNode;
 	readonly parent: GeneralParentNode;

package/src/client/InputNode.ts

@@ -0,0 +1,113 @@
+import type { RuntimeInputValue, RuntimeValue } from '../lib/codecs/getSharedValueCodec.ts';
+import type { InputControlDefinition } from '../parse/body/control/InputControlDefinition.ts';
+import type { LeafNodeDefinition } from '../parse/model/LeafNodeDefinition.ts';
+import type { BaseValueNode, BaseValueNodeState } from './BaseValueNode.ts';
+import type { NodeAppearances } from './NodeAppearances.ts';
+import type { RootNode } from './RootNode.ts';
+import type { ValueType } from './ValueType.ts';
+import type { GeneralParentNode } from './hierarchy.ts';
+import type { LeafNodeValidationState } from './validation.ts';
+
+export type InputValue<V extends ValueType> = RuntimeValue<V>;
+
+export type InputNodeInputValue<V extends ValueType> = RuntimeInputValue<V>;
+
+export interface InputNodeState<V extends ValueType> extends BaseValueNodeState<InputValue<V>> {
+	get children(): null;
+	get valueOptions(): null;
+
+	/**
+	 * Reflects the current value of a {@link InputNode}. This value may be
+	 * populated when a form is loaded, and it may be updated by certain
+	 * computations defined by the form. It may also be updated by a client, using
+	 * the {@link InputNode.setValue} method.
+	 */
+	get value(): InputValue<V>;
+}
+
+export interface InputDefinition<V extends ValueType = ValueType> extends LeafNodeDefinition<V> {
+	readonly bodyElement: InputControlDefinition;
+}
+
+export type InputNodeAppearances = NodeAppearances<InputDefinition>;
+
+interface StringInputNodeOptions {
+	readonly rows: number | null;
+}
+
+interface GeoInputNodeOptions {
+	readonly accuracyThreshold: number | null;
+	readonly unacceptableAccuracyThreshold: number | null;
+}
+
+interface InputNodeOptionsByValueType {
+	readonly string: StringInputNodeOptions;
+	readonly int: null;
+	readonly boolean: null;
+	readonly decimal: null;
+	readonly date: null;
+	readonly time: null;
+	readonly dateTime: null;
+	readonly geopoint: GeoInputNodeOptions;
+	readonly geotrace: GeoInputNodeOptions;
+	readonly geoshape: GeoInputNodeOptions;
+	readonly binary: null;
+	readonly barcode: null;
+	readonly intent: null;
+}
+
+export type InputNodeOptions<V extends ValueType> = InputNodeOptionsByValueType[V];
+
+/**
+ * A node corresponding to form field defined as an
+ * {@link https://getodk.github.io/xforms-spec/#body-elements | XForms `<input>`},
+ * which a user-facing client would likely present for a user to fill.
+ */
+export interface InputNode<V extends ValueType = ValueType>
+	extends BaseValueNode<V, InputValue<V>> {
+	readonly nodeType: 'input';
+	readonly valueType: V;
+	readonly appearances: InputNodeAppearances;
+	readonly nodeOptions: InputNodeOptions<V>;
+	readonly definition: InputDefinition<V>;
+	readonly root: RootNode;
+	readonly parent: GeneralParentNode;
+	readonly currentState: InputNodeState<V>;
+	readonly validationState: LeafNodeValidationState;
+
+	/**
+	 * For use by a client to update the value of an {@link InputNode}.
+	 */
+	setValue(value: InputNodeInputValue<V>): RootNode;
+}
+
+export type StringInputValue = InputValue<'string'>;
+export type IntInputValue = InputValue<'int'>;
+export type DecimalInputValue = InputValue<'decimal'>;
+export type GeopointInputValue = InputValue<'geopoint'>;
+
+export type StringInputNode = InputNode<'string'>;
+export type IntInputNode = InputNode<'int'>;
+export type DecimalInputNode = InputNode<'decimal'>;
+export type GeopointInputNode = InputNode<'geopoint'>;
+
+// prettier-ignore
+type SupportedInputValueType =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| 'string'
+	| 'int'
+	| 'decimal'
+	| 'geopoint';
+
+type TemporaryStringValueType = Exclude<ValueType, SupportedInputValueType>;
+
+export type TemporaryStringValueInputNode = InputNode<TemporaryStringValueType>;
+
+// prettier-ignore
+export type AnyInputNode =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| StringInputNode
+	| IntInputNode
+	| DecimalInputNode
+	| GeopointInputNode
+	| TemporaryStringValueInputNode;

package/src/client/ModelValueNode.ts

@@ -1,10 +1,15 @@
+import type { RuntimeValue } from '../lib/codecs/getSharedValueCodec.ts';
 import type { LeafNodeDefinition } from '../parse/model/LeafNodeDefinition.ts';
-import type { BaseNode, BaseNodeState } from './BaseNode.ts';
+import type { BaseValueNode, BaseValueNodeState } from './BaseValueNode.ts';
 import type { GeneralParentNode } from './hierarchy.ts';
 import type { RootNode } from './RootNode.ts';
 import type { LeafNodeValidationState } from './validation.ts';
+import type { ValueType } from './ValueType.ts';
 
-export interface ModelValueNodeState extends BaseNodeState {
+export type ModelValue<V extends ValueType> = RuntimeValue<V>;
+
+export interface ModelValueNodeState<V extends ValueType>
+	extends BaseValueNodeState<ModelValue<V>> {
 	get label(): null;
 	get hint(): null;
 	get children(): null;
@@ -15,10 +20,11 @@ export interface ModelValueNodeState extends BaseNodeState {
 	 * populated when a form is loaded, and it may be updated by certain
 	 * computations defined by the form.
 	 */
-	get value(): string;
+	get value(): ModelValue<V>;
 }
 
-export interface ModelValueDefinition extends LeafNodeDefinition {
+export interface ModelValueDefinition<V extends ValueType = ValueType>
+	extends LeafNodeDefinition<V> {
 	readonly bodyElement: null;
 }
 
@@ -29,12 +35,30 @@ export interface ModelValueDefinition extends LeafNodeDefinition {
  * - a leaf/value node (i.e. it has no element children; it may be defined in
  *   the form's `<model>` as either an {@link Element} or {@link Attr})
  */
-export interface ModelValueNode extends BaseNode {
+export interface ModelValueNode<V extends ValueType = ValueType>
+	extends BaseValueNode<V, ModelValue<V>> {
 	readonly nodeType: 'model-value';
+	readonly valueType: V;
 	readonly appearances: null;
-	readonly definition: ModelValueDefinition;
+	readonly nodeOptions: null;
+	readonly definition: ModelValueDefinition<V>;
 	readonly root: RootNode;
 	readonly parent: GeneralParentNode;
-	readonly currentState: ModelValueNodeState;
+	readonly currentState: ModelValueNodeState<V>;
 	readonly validationState: LeafNodeValidationState;
 }
+
+export type AnyModelValueNode =
+	| ModelValueNode<'barcode'>
+	| ModelValueNode<'binary'>
+	| ModelValueNode<'boolean'>
+	| ModelValueNode<'date'>
+	| ModelValueNode<'dateTime'>
+	| ModelValueNode<'decimal'>
+	| ModelValueNode<'geopoint'>
+	| ModelValueNode<'geoshape'>
+	| ModelValueNode<'geotrace'>
+	| ModelValueNode<'int'>
+	| ModelValueNode<'intent'>
+	| ModelValueNode<'string'>
+	| ModelValueNode<'time'>;

package/src/client/NoteNode.ts

@@ -1,13 +1,17 @@
-import type { InputDefinition } from '../parse/body/control/InputDefinition.ts';
+import type { NoteRuntimeValue } from '../lib/codecs/NoteCodec.ts';
+import type { InputControlDefinition } from '../parse/body/control/InputControlDefinition.ts';
 import type { LeafNodeDefinition } from '../parse/model/LeafNodeDefinition.ts';
-import type { BaseNode, BaseNodeState } from './BaseNode.ts';
+import type { BaseValueNode, BaseValueNodeState } from './BaseValueNode.ts';
 import type { GeneralParentNode } from './hierarchy.ts';
 import type { NodeAppearances } from './NodeAppearances.ts';
 import type { RootNode } from './RootNode.ts';
 import type { TextRange } from './TextRange.ts';
 import type { LeafNodeValidationState } from './validation.ts';
+import type { ValueType } from './ValueType.ts';
 
-export interface NoteNodeState extends BaseNodeState {
+export type NoteValue<V extends ValueType> = NoteRuntimeValue<V>;
+
+export interface NoteNodeState<V extends ValueType> extends BaseValueNodeState<NoteValue<V>> {
 	/**
 	 * Note-specific specialization: a note will always have a non-null value in
 	 * at least one of:
@@ -48,11 +52,11 @@ export interface NoteNodeState extends BaseNodeState {
 	// node types, specifically to make a clear distinction between blank and
 	// non-blank values (as that has been a primary driver for prioritizing note
 	// functionality).
-	get value(): string | null;
+	get value(): NoteValue<V>;
 }
 
-export interface NoteDefinition extends LeafNodeDefinition {
-	readonly bodyElement: InputDefinition;
+export interface NoteDefinition<V extends ValueType = ValueType> extends LeafNodeDefinition<V> {
+	readonly bodyElement: InputControlDefinition;
 }
 
 export type NoteNodeAppearances = NodeAppearances<NoteDefinition>;
@@ -63,12 +67,44 @@ export type NoteNodeAppearances = NodeAppearances<NoteDefinition>;
  * - associated with an input, with at least one text element (label or hint)
  * - guaranteed to be {@link NoteNodeState.readonly | readonly}
  */
-export interface NoteNode extends BaseNode {
+export interface NoteNode<V extends ValueType = ValueType> extends BaseValueNode<V, NoteValue<V>> {
 	readonly nodeType: 'note';
 	readonly appearances: NoteNodeAppearances;
-	readonly definition: NoteDefinition;
+	readonly nodeOptions: null;
+	readonly definition: NoteDefinition<V>;
 	readonly root: RootNode;
 	readonly parent: GeneralParentNode;
-	readonly currentState: NoteNodeState;
+	readonly currentState: NoteNodeState<V>;
 	readonly validationState: LeafNodeValidationState;
 }
+
+export type StringNoteValue = NoteValue<'string'>;
+export type IntNoteValue = NoteValue<'int'>;
+export type DecimalNoteValue = NoteValue<'decimal'>;
+export type GeopointNoteValue = NoteValue<'geopoint'>;
+
+export type StringNoteNode = NoteNode<'string'>;
+export type IntNoteNode = NoteNode<'int'>;
+export type DecimalNoteNode = NoteNode<'decimal'>;
+export type GeopointNoteNode = NoteNode<'geopoint'>;
+
+// prettier-ignore
+type SupportedNoteValueType =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| 'string'
+	| 'int'
+	| 'decimal'
+	| 'geopoint';
+
+type TemporaryStringValueType = Exclude<ValueType, SupportedNoteValueType>;
+
+export type TemporaryStringValueNoteNode = NoteNode<TemporaryStringValueType>;
+
+// prettier-ignore
+export type AnyNoteNode =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| StringNoteNode
+	| IntNoteNode
+	| DecimalNoteNode
+	| GeopointNoteNode
+	| TemporaryStringValueNoteNode;

package/src/client/RangeNode.ts

@@ -0,0 +1,51 @@
+import type { RuntimeInputValue, RuntimeValue } from '../lib/codecs/getSharedValueCodec.ts';
+import type { RangeNodeDefinition, RangeValueType } from '../parse/model/RangeNodeDefinition.ts';
+import type { BaseValueNode, BaseValueNodeState } from './BaseValueNode.ts';
+import type { NodeAppearances } from './NodeAppearances.ts';
+import type { RootNode } from './RootNode.ts';
+import type { GeneralParentNode } from './hierarchy.ts';
+import type { LeafNodeValidationState } from './validation.ts';
+
+export type { RangeValueType };
+
+export type RangeValue<V extends RangeValueType> = RuntimeValue<V>;
+
+export type RangeInputValue<V extends RangeValueType> = RuntimeInputValue<V>;
+
+export interface RangeNodeState<V extends RangeValueType>
+	extends BaseValueNodeState<RangeValue<V>> {
+	get valueOptions(): null;
+}
+
+export type RangeNodeAppearances = NodeAppearances<RangeNodeDefinition>;
+
+/**
+ * A node corresponding to form field defined as an
+ * {@link https://getodk.github.io/xforms-spec/#body-elements | XForms `<range>`}.
+ */
+export interface RangeNode<V extends RangeValueType = RangeValueType>
+	extends BaseValueNode<V, RangeValue<V>> {
+	readonly nodeType: 'range';
+	readonly valueType: V;
+	readonly appearances: RangeNodeAppearances;
+	readonly nodeOptions: null;
+	readonly definition: RangeNodeDefinition<V>;
+	readonly root: RootNode;
+	readonly parent: GeneralParentNode;
+	readonly currentState: RangeNodeState<V>;
+	readonly validationState: LeafNodeValidationState;
+
+	/**
+	 * For use by a client to update the value of an {@link RangeNode}.
+	 */
+	setValue(value: RangeInputValue<V>): RootNode;
+}
+
+export type IntRangeNode = RangeNode<'int'>;
+export type DecimalRangeNode = RangeNode<'decimal'>;
+
+// prettier-ignore
+export type AnyRangeNode =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| IntRangeNode
+	| DecimalRangeNode;

package/src/client/RankNode.ts

@@ -0,0 +1,54 @@
+import type { RankControlDefinition } from '../parse/body/control/RankControlDefinition.ts';
+import type { LeafNodeDefinition } from '../parse/model/LeafNodeDefinition.ts';
+import type { BaseValueNode, BaseValueNodeState } from './BaseValueNode.ts';
+import type { RootNode } from './RootNode.ts';
+import type { TextRange } from './TextRange.ts';
+import type { GeneralParentNode } from './hierarchy.ts';
+import type { LeafNodeValidationState } from './validation.ts';
+import type { UnknownAppearanceDefinition } from '../parse/body/appearance/unknownAppearanceParser.ts';
+import type { ValueType } from './ValueType.ts';
+
+export interface RankItem {
+	get label(): TextRange<'item-label'>;
+	get value(): string;
+}
+
+export type RankValueOptions = readonly RankItem[];
+
+export interface RankNodeState extends BaseValueNodeState<readonly string[]> {
+	get valueOptions(): RankValueOptions;
+
+	/**
+	 * An ordered collection of values from {@link RankItem}.
+	 * The order of the items is important and must be preserved during processing.
+	 */
+	get value(): readonly string[];
+}
+
+export interface RankDefinition<V extends ValueType = ValueType> extends LeafNodeDefinition<V> {
+	readonly bodyElement: RankControlDefinition;
+}
+
+export interface RankNode extends BaseValueNode<'string', readonly string[]> {
+	readonly nodeType: 'rank';
+	readonly appearances: UnknownAppearanceDefinition;
+	readonly nodeOptions: null;
+	readonly valueType: 'string';
+	readonly definition: RankDefinition<'string'>;
+	readonly root: RootNode;
+	readonly parent: GeneralParentNode;
+	readonly currentState: RankNodeState;
+	readonly validationState: LeafNodeValidationState;
+
+	/**
+	 * Convenience API to get the {@link RankItem}'s label.
+	 */
+	getValueLabel(value: string): TextRange<'item-label'> | null;
+
+	/**
+	 * Set the value which is an ordered collection of values from {@link RankItem}.
+	 * Calling this setter replaces the currently value.
+	 * If called with an empty array, the current is cleared.
+	 */
+	setValues(values: readonly string[]): RootNode;
+}