@getodk/xforms-engine 0.5.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getodk/xforms-engine",
-  "version": "0.5.0",
+  "version": "0.7.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.9.0",
+    "node": "^18.20.5 || ^20.18.1 || ^22.12.0",
     "yarn": "1.22.22"
   },
   "scripts": {
@@ -55,30 +55,33 @@
   },
   "dependencies": {
     "papaparse": "^5.4.1",
-    "solid-js": "^1.9.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.3.0",
-    "@playwright/test": "^1.47.2",
+    "@getodk/xpath": "0.4.0",
+    "@playwright/test": "^1.49.1",
     "@types/papaparse": "^5.3.15",
-    "@vitest/browser": "^2.1.1",
+    "@vitest/browser": "^2.1.8",
     "babel-plugin-transform-jsbi-to-bigint": "^1.4.0",
     "http-server": "^14.1.1",
     "jsdom": "^25.0.1",
-    "typedoc": "^0.26.7",
-    "vite": "^5.4.8",
-    "vite-plugin-dts": "^4.2.2",
+    "typedoc": "^0.27.5",
+    "vite": "^5.4.11",
+    "vite-plugin-dts": "^4.3.0",
     "vite-plugin-no-bundle": "^4.0.0",
-    "vitest": "^2.1.1"
+    "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

@@ -5,7 +5,7 @@ import type { OpaqueReactiveObjectFactory } from './OpaqueReactiveObjectFactory.
 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 { InstanceState } from './serialization/InstanceState.ts';
 import type {
 	AncestorNodeValidationState,
 	LeafNodeValidationState,
@@ -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
@@ -251,14 +256,14 @@ export interface BaseNode {
 	readonly validationState: NodeValidationState;
 
 	/**
-	 * Represents the current submission state of the node.
+	 * Represents the current instance state of the node.
 	 *
-	 * @see {@link SubmissionState.submissionXML} for additional detail.
+	 * @see {@link InstanceState.instanceXML} 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;
+	readonly instanceState: InstanceState;
 }

package/src/client/BaseValueNode.ts

@@ -2,12 +2,13 @@ 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 { InstanceState } from './serialization/InstanceState.ts';
 import type { LeafNodeValidationState } from './validation.ts';
 import type { ValueType } from './ValueType.ts';
 
 export interface BaseValueNodeState<Value> extends BaseNodeState {
 	get children(): null;
-	get valueOptions(): null;
+	get valueOptions(): unknown;
 	get value(): Value;
 
 	/**
@@ -15,12 +16,14 @@ export interface BaseValueNodeState<Value> extends BaseNodeState {
 	 * {@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)
+	 * - would be serialized as a text node in {@link InstanceState.instanceXML}
+	 *   (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
+	 *
+	 * @todo Consider moving into {@link InstanceState}
 	 */
 	get instanceValue(): string;
 }
@@ -32,4 +35,5 @@ export interface BaseValueNode<V extends ValueType = ValueType, Value = string>
 	readonly parent: GeneralParentNode;
 	readonly currentState: BaseValueNodeState<Value>;
 	readonly validationState: LeafNodeValidationState;
+	readonly instanceState: InstanceState;
 }

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

@@ -31,16 +31,44 @@ export interface InputDefinition<V extends ValueType = ValueType> extends LeafNo
 
 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..
+ * 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;
@@ -53,16 +81,23 @@ export interface InputNode<V extends ValueType = ValueType>
 	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';
+	| 'decimal'
+	| 'geopoint';
 
 type TemporaryStringValueType = Exclude<ValueType, SupportedInputValueType>;
 
@@ -74,4 +109,5 @@ export type AnyInputNode =
 	| StringInputNode
 	| IntInputNode
 	| DecimalInputNode
+	| GeopointInputNode
 	| TemporaryStringValueInputNode;

package/src/client/ModelValueNode.ts

@@ -40,6 +40,7 @@ export interface ModelValueNode<V extends ValueType = ValueType>
 	readonly nodeType: 'model-value';
 	readonly valueType: V;
 	readonly appearances: null;
+	readonly nodeOptions: null;
 	readonly definition: ModelValueDefinition<V>;
 	readonly root: RootNode;
 	readonly parent: GeneralParentNode;

package/src/client/NoteNode.ts

@@ -1,13 +1,17 @@
+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,10 +52,10 @@ 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 {
+export interface NoteDefinition<V extends ValueType = ValueType> extends LeafNodeDefinition<V> {
 	readonly bodyElement: InputControlDefinition;
 }
 
@@ -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;
+}

package/src/client/RootNode.ts

@@ -3,8 +3,12 @@ import type { RootDefinition } from '../parse/model/RootDefinition.ts';
 import type { BaseNode, BaseNodeState } from './BaseNode.ts';
 import type { ActiveLanguage, FormLanguage, FormLanguages } from './FormLanguage.ts';
 import type { GeneralChildNode } from './hierarchy.ts';
-import type { SubmissionChunkedType, SubmissionOptions } from './submission/SubmissionOptions.ts';
-import type { SubmissionResult } from './submission/SubmissionResult.ts';
+import type {
+	ChunkedInstancePayload,
+	InstancePayload,
+	MonolithicInstancePayload,
+} from './serialization/InstancePayload.ts';
+import type { InstancePayloadOptions } from './serialization/InstancePayloadOptions.ts';
 import type { AncestorNodeValidationState } from './validation.ts';
 
 export interface RootNodeState extends BaseNodeState {
@@ -29,6 +33,8 @@ export interface RootNode extends BaseNode {
 	 */
 	readonly appearances: null;
 
+	readonly nodeOptions: null;
+
 	/**
 	 * @todo This is another odd deviation in {@link RootNode}. Unlike
 	 * {@link languages}, it doesn't feel particularly **essential**. While it
@@ -58,33 +64,41 @@ export interface RootNode extends BaseNode {
 	setLanguage(language: FormLanguage): RootNode;
 
 	/**
-	 * Prepares the current form instance state for submission.
+	 * Prepares the current form instance state as an {@link InstancePayload}.
 	 *
-	 * A {@link SubmissionResult} will be prepared even if the current form state
-	 * includes `constraint` or `required` violations. This is intended to serve
-	 * two purposes:
+	 * A payload will be prepared even if the current form state includes
+	 * `constraint` or `required` violations. This supports serveral purposes:
 	 *
-	 * - A client may effectively use this method as a part of its own "submit"
-	 *   routine, and use any violations included in the {@link SubmissionResult}
+	 * - A client may effectively use this method as a part of its "submit"
+	 *   workflow, and use any violations included in the {@link InstancePayload}
 	 *   to prompt users to address those violations.
 	 *
-	 * - A client may inspect the submission state of a form at any time.
+	 * - A client may inspect the serialized instance state of a form at any time.
 	 *   Depending on the client and use case, this may be a convenience (e.g. for
 	 *   developers to inspect that form state at a current point in time); or it
 	 *   may provide necessary functionality (e.g. for test or tooling clients).
 	 *
-	 * Note on asynchrony: preparing a {@link SubmissionResult} is expected to be
-	 * a fast operation. It may even be nearly instantaneous, or roughly
+	 * - A client may capture _incomplete_ instance state (e.g. for storage in
+	 *   client-side storage or similar persistance layer), to resume filling the
+	 *   instance at a later time.
+	 *
+	 * Note on asynchrony: preparing a {@link InstancePayload} is expected to be a
+	 * fast operation. It may even be nearly instantaneous, or roughly
 	 * proportionate to the size of the form itself. However, this method is
 	 * designed to be asynchronous out of an abundance of caution, anticipating
 	 * that some as-yet undeveloped operations on binary data (e.g. form
 	 * attachments) may themselves impose asynchrony (i.e. by interfaces provided
 	 * by the platform and/or external dependencies).
 	 *
-	 * A client may specify {@link SubmissionOptions<'chunked'>}, in which case a
-	 * {@link SubmissionResult<'chunked'>} will be produced, with form attachments
+	 * A client may specify {@link InstancePayloadOptions<'chunked'>}, in which
+	 * case a {@link ChunkedInstancePayload} will be produced, with form
+	 * attachments
 	 */
-	prepareSubmission<ChunkedType extends SubmissionChunkedType>(
-		options?: SubmissionOptions<ChunkedType>
-	): Promise<SubmissionResult<ChunkedType>>;
+	prepareInstancePayload(): Promise<MonolithicInstancePayload>;
+	prepareInstancePayload(
+		options: InstancePayloadOptions<'monolithic'>
+	): Promise<MonolithicInstancePayload>;
+	prepareInstancePayload(
+		options: InstancePayloadOptions<'chunked'>
+	): Promise<ChunkedInstancePayload>;
 }

package/src/client/SelectNode.ts

@@ -1,24 +1,26 @@
-import type { AnySelectDefinition } from '../parse/body/control/select/SelectDefinition.ts';
+import type {
+	AnySelectControlDefinition,
+	SelectType,
+} from '../parse/body/control/SelectControlDefinition.ts';
 import type { LeafNodeDefinition } from '../parse/model/LeafNodeDefinition.ts';
-import type { BaseNode, BaseNodeState } from './BaseNode.ts';
-import type { InputNode } from './InputNode.ts';
+import type { BaseValueNode, BaseValueNodeState } from './BaseValueNode.ts';
 import type { NodeAppearances } from './NodeAppearances.ts';
 import type { RootNode } from './RootNode.ts';
 import type { TextRange } from './TextRange.ts';
+import type { ValueType } from './ValueType.ts';
 import type { GeneralParentNode } from './hierarchy.ts';
 import type { LeafNodeValidationState } from './validation.ts';
 
 export interface SelectItem {
+	get label(): TextRange<'item-label'>;
 	get value(): string;
-	get label(): TextRange<'item-label'> | null;
 }
 
-export interface SelectNodeState extends BaseNodeState {
+export type SelectValueOptions = readonly SelectItem[];
+
+export interface SelectNodeState extends BaseValueNodeState<readonly string[]> {
 	get children(): null;
 
-	/**
-	 * @todo should {@link BaseNodeState} include this??
-	 */
 	get valueOptions(): readonly SelectItem[];
 
 	/**
@@ -33,43 +35,68 @@ export interface SelectNodeState extends BaseNodeState {
 	 * Should a `SelectNodeState` have this `value` type, whereas a hypothetical
 	 * `Select1NodeState` would have `get value(): SelectItem | null`?
 	 */
-	get value(): readonly SelectItem[];
+	get value(): readonly string[];
 }
 
-export interface SelectDefinition extends LeafNodeDefinition {
-	readonly bodyElement: AnySelectDefinition;
+export interface SelectDefinition<V extends ValueType = ValueType> extends LeafNodeDefinition<V> {
+	readonly bodyElement: AnySelectControlDefinition;
 }
 
 export type SelectNodeAppearances = NodeAppearances<SelectDefinition>;
 
-export interface SelectNode extends BaseNode {
+export interface SelectNode extends BaseValueNode<'string', readonly string[]> {
 	readonly nodeType: 'select';
+	readonly valueType: 'string';
+	readonly selectType: SelectType;
 	readonly appearances: SelectNodeAppearances;
-	readonly definition: SelectDefinition;
+	readonly nodeOptions: null;
+	readonly definition: SelectDefinition<'string'>;
 	readonly root: RootNode;
 	readonly parent: GeneralParentNode;
 	readonly currentState: SelectNodeState;
 	readonly validationState: LeafNodeValidationState;
 
 	/**
-	 * For use by a client to update the selection of a select node where:
+	 * Convenience API to get the {@link SelectItem} which is associated with
+	 * {@link value}, if one is currently available—i.e. if it is present in
+	 * {@link SelectNodeState.valueOptions}.
+	 */
+	getValueOption(value: string): SelectItem | null;
+
+	/**
+	 * Convenience API to determine if {@link value} is currently selected—i.e. if
+	 * it is one of the selected values in {@link SelectNodeState.value}.
+	 */
+	isSelected(value: string): boolean;
+
+	/**
+	 * Selects a single {@link value}, as provided by a {@link SelectItem.value}.
+	 * Calling this setter replaces the currently selected value(s, if any),
+	 * where:
 	 *
-	 * - For fields defined with an XForms `<select>`, calling this method is
-	 *   additive, i.e. it will include the item in its
-	 *   {@link SelectNodeState.value}.
-	 * - For fields defined with an XForms `<select1>`, calling this method will
-	 *   replace the selection (if any).
+	 * - if the provided value is `null`, the current selection is cleared; ELSE
+	 * - the provided value is selected in place of any currently selected values.
 	 *
-	 * @todo @see {@link InputNode.setValue} re: write restrictions
-	 * @todo @see {@link SelectNodeState.value} re: breaking up the types
+	 * This setter is most useful for {@link SelectNode}s associated with an
+	 * XForms
+	 * {@link https://getodk.github.io/xforms-spec/#body-elements | `<select1>`}
+	 * control.
 	 */
-	select(item: SelectItem): RootNode;
+	selectValue(value: string | null): RootNode;
 
 	/**
-	 * For use by a client to remove an item from the node's
-	 * {@link SelectNodeState.value}.
+	 * Selects any number of {@link values}, as provided by any number of
+	 * {@link SelectItem.value}s. Calling this setter replaces the currently
+	 * selected value(s, if any). If called with an empty array, the current
+	 * selection is cleared.
+	 *
+	 * This setter is most useful for {@link SelectNode}s associated with an
+	 * XForms
+	 * {@link https://getodk.github.io/xforms-spec/#body-elements | `<select>`}
+	 * control.
 	 *
-	 * @todo @see {@link InputNode.setValue} re: write restrictions
+	 * This setter _may_ be used with a `<select1>` control, in which case the
+	 * provided {@link values} should produce at most one value.
 	 */
-	deselect(item: SelectItem): RootNode;
+	selectValues(values: readonly string[]): RootNode;
 }

package/src/client/SubtreeNode.ts

@@ -52,6 +52,7 @@ export interface SubtreeDefinition extends BaseSubtreeDefinition {
 export interface SubtreeNode extends BaseNode {
 	readonly nodeType: 'subtree';
 	readonly appearances: null;
+	readonly nodeOptions: null;
 	readonly definition: SubtreeDefinition;
 	readonly root: RootNode;
 	readonly parent: GeneralParentNode;