@getodk/xforms-engine 0.3.0 → 0.5.0

package/src/error/XPathFunctionalityError.ts

@@ -0,0 +1,26 @@
+import type { AnyFunction, ExpandUnion } from '@getodk/common/types/helpers.js';
+import type { XPathDOMAdapter, XPathNode } from '@getodk/xpath';
+
+/**
+ * @todo this is general enough to go in `@getodk/common`. Holding off until
+ * it's clear we actually benefit from this particular type gymnastic.
+ */
+// prettier-ignore
+type MethodNameOf<T> = {
+	[K in keyof T]:
+		T[K] extends AnyFunction
+			? K
+			: never;
+}[keyof T];
+
+// prettier-ignore
+export type XPathFunctionalityErrorCategory = ExpandUnion<
+	| MethodNameOf<XPathDOMAdapter<XPathNode>>
+	| 'processing-instruction'
+>;
+
+export abstract class XPathFunctionalityError extends Error {
+	constructor(functionalityMessagePrefix: string, category: XPathFunctionalityErrorCategory) {
+		super(`${functionalityMessagePrefix}${category}`);
+	}
+}

package/src/error/XPathFunctionalityNotSupportedError.ts

@@ -0,0 +1,18 @@
+import type { XPathFunctionalityErrorCategory } from './XPathFunctionalityError.ts';
+import { XPathFunctionalityError } from './XPathFunctionalityError.ts';
+
+type XPathFunctionalityNotSupportedStub = () => never;
+
+export class XPathFunctionalityNotSupportedError extends XPathFunctionalityError {
+	static createStubImplementation(
+		category: XPathFunctionalityErrorCategory
+	): XPathFunctionalityNotSupportedStub {
+		return () => {
+			throw new this(category);
+		};
+	}
+
+	private constructor(category: XPathFunctionalityErrorCategory) {
+		super('XPath functionality not supported: ', category);
+	}
+}

package/src/error/XPathFunctionalityPendingError.ts

@@ -0,0 +1,18 @@
+import type { XPathFunctionalityErrorCategory } from './XPathFunctionalityError.ts';
+import { XPathFunctionalityError } from './XPathFunctionalityError.ts';
+
+type XPathFunctionalityPendingStub = () => never;
+
+export class XPathFunctionalityPendingError extends XPathFunctionalityError {
+	static createStubImplementation(
+		category: XPathFunctionalityErrorCategory
+	): XPathFunctionalityPendingStub {
+		return () => {
+			throw new this(category);
+		};
+	}
+
+	private constructor(category: XPathFunctionalityErrorCategory) {
+		super('XPath functionality pending: ', category);
+	}
+}

package/src/index.ts

@@ -3,6 +3,7 @@ import { initializeForm as engine__initializeForm } from './instance/index.ts';
 
 export const initializeForm: InitializeForm = engine__initializeForm;
 
+export type * from './client/constants.ts';
 export * as constants from './client/constants.ts';
 export type * from './client/EngineConfig.ts';
 export type * from './client/FormLanguage.ts';
@@ -13,23 +14,36 @@ export type {
 	AnyLeafNode,
 	AnyNode,
 	AnyParentNode,
+	AnyUnsupportedControlNode,
 	GeneralChildNode,
 	GeneralParentNode,
 	RepeatRangeNode,
 } from './client/hierarchy.ts';
 export type * from './client/index.ts';
+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/repeat/RepeatInstanceNode.ts';
 export type * from './client/repeat/RepeatRangeControlledNode.ts';
 export type * from './client/repeat/RepeatRangeUncontrolledNode.ts';
+export type * from './client/resources.ts';
 export type * from './client/RootNode.ts';
 export type * from './client/SelectNode.ts';
-export type * from './client/StringNode.ts';
+export type * from './client/submission/SubmissionData.ts';
+export type * from './client/submission/SubmissionDefinition.ts';
+export type * from './client/submission/SubmissionInstanceFile.ts';
+export type * from './client/submission/SubmissionOptions.ts';
+export type * from './client/submission/SubmissionResult.ts';
+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/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
@@ -39,4 +53,4 @@ export type * from './client/validation.ts';
 export type {
 	AnySelectDefinition,
 	SelectDefinition,
-} from './body/control/select/SelectDefinition.ts';
+} from './parse/body/control/select/SelectDefinition.ts';

package/src/instance/Group.ts

@@ -1,7 +1,12 @@
+import { XPathNodeKindKey } from '@getodk/xpath';
 import type { Accessor } from 'solid-js';
 import type { GroupDefinition, GroupNode, GroupNodeAppearances } from '../client/GroupNode.ts';
+import type { FormNodeID } from '../client/identity.ts';
+import type { SubmissionState } from '../client/submission/SubmissionState.ts';
 import type { TextRange } from '../client/TextRange.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 type { ChildrenState } from '../lib/reactivity/createChildrenState.ts';
 import { createChildrenState } from '../lib/reactivity/createChildrenState.ts';
 import type { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
@@ -16,25 +21,30 @@ import type { DescendantNodeSharedStateSpec } from './abstract/DescendantNode.ts
 import { DescendantNode } from './abstract/DescendantNode.ts';
 import { buildChildren } from './children.ts';
 import type { GeneralChildNode, GeneralParentNode } from './hierarchy.ts';
-import type { NodeID } from './identity.ts';
 import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
-import type { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
+import type { ClientReactiveSubmittableParentNode } from './internal-api/submission/ClientReactiveSubmittableParentNode.ts';
 
 // prettier-ignore
 interface GroupStateSpec extends DescendantNodeSharedStateSpec {
 	readonly label: Accessor<TextRange<'label'> | null>;
 	readonly hint: null;
-	readonly children: Accessor<readonly NodeID[]>;
+	readonly children: Accessor<readonly FormNodeID[]>;
 	readonly valueOptions: null;
 	readonly value: null;
 }
 
 export class Group
-	extends DescendantNode<GroupDefinition, GroupStateSpec, GeneralChildNode>
-	implements GroupNode, EvaluationContext, SubscribableDependency
+	extends DescendantNode<GroupDefinition, GroupStateSpec, GeneralParentNode, GeneralChildNode>
+	implements
+		GroupNode,
+		XFormsXPathElement,
+		EvaluationContext,
+		ClientReactiveSubmittableParentNode<GeneralChildNode>
 {
 	private readonly childrenState: ChildrenState<GeneralChildNode>;
 
+	override readonly [XPathNodeKindKey] = 'element';
+
 	// InstanceNode
 	protected readonly state: SharedNodeState<GroupStateSpec>;
 	protected override engineState: EngineState<GroupStateSpec>;
@@ -44,6 +54,7 @@ export class Group
 	readonly appearances: GroupNodeAppearances;
 	readonly currentState: MaterializedChildren<CurrentState<GroupStateSpec>, GeneralChildNode>;
 	readonly validationState: AncestorNodeValidationState;
+	readonly submissionState: SubmissionState;
 
 	constructor(parent: GeneralParentNode, definition: GroupDefinition) {
 		super(parent, definition);
@@ -85,6 +96,7 @@ export class Group
 
 		childrenState.setChildren(buildChildren(this));
 		this.validationState = createAggregatedViolations(this, sharedStateOptions);
+		this.submissionState = createParentNodeSubmissionState(this);
 	}
 
 	getChildren(): readonly GeneralChildNode[] {

package/src/instance/InputControl.ts

@@ -0,0 +1,119 @@
+import { XPathNodeKindKey } from '@getodk/xpath';
+import type { Accessor } from 'solid-js';
+import type {
+	InputDefinition,
+	InputNode,
+	InputNodeAppearances,
+	InputNodeInputValue,
+} from '../client/InputNode.ts';
+import type { TextRange } from '../client/TextRange.ts';
+import type { ValueType } from '../client/ValueType.ts';
+import type { XFormsXPathElement } from '../integration/xpath/adapter/XFormsXPathNode.ts';
+import type { RuntimeInputValue, RuntimeValue } from '../lib/codecs/getSharedValueCodec.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 { 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';
+
+export type AnyInputDefinition = {
+	[V in ValueType]: InputDefinition<V>;
+}[ValueType];
+
+interface InputControlStateSpec<V extends ValueType> extends ValueNodeStateSpec<RuntimeValue<V>> {
+	readonly label: Accessor<TextRange<'label'> | null>;
+	readonly hint: Accessor<TextRange<'hint'> | null>;
+}
+
+export class InputControl<V extends ValueType = ValueType>
+	extends ValueNode<V, InputDefinition<V>, RuntimeValue<V>, RuntimeInputValue<V>>
+	implements
+		InputNode<V>,
+		XFormsXPathElement,
+		EvaluationContext,
+		ValidationContext,
+		ClientReactiveSubmittableValueNode
+{
+	static from(parent: GeneralParentNode, definition: InputDefinition): AnyInputControl;
+	static from<V extends ValueType>(
+		parent: GeneralParentNode,
+		definition: InputDefinition<V>
+	): InputControl<V> {
+		return new this(parent, definition);
+	}
+
+	// XFormsXPathElement
+	override readonly [XPathNodeKindKey] = 'element';
+
+	// InstanceNode
+	protected readonly state: SharedNodeState<InputControlStateSpec<V>>;
+	protected readonly engineState: EngineState<InputControlStateSpec<V>>;
+
+	// InputNode
+	readonly nodeType = 'input';
+	readonly appearances: InputNodeAppearances;
+	readonly currentState: CurrentState<InputControlStateSpec<V>>;
+
+	constructor(parent: GeneralParentNode, definition: InputDefinition<V>) {
+		const codec = getSharedValueCodec(definition.valueType);
+
+		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: InputNodeInputValue<V>): Root {
+		this.setValueState(value);
+
+		return this.root;
+	}
+}
+
+export type AnyInputControl =
+	| InputControl<'barcode'>
+	| InputControl<'binary'>
+	| InputControl<'boolean'>
+	| InputControl<'date'>
+	| InputControl<'dateTime'>
+	| InputControl<'decimal'>
+	| InputControl<'geopoint'>
+	| InputControl<'geoshape'>
+	| InputControl<'geotrace'>
+	| InputControl<'int'>
+	| InputControl<'intent'>
+	| InputControl<'string'>
+	| InputControl<'time'>;

package/src/instance/ModelValue.ts

@@ -1,65 +1,57 @@
-import { identity } from '@getodk/common/lib/identity.ts';
-import type { ModelValueNode } from '../client/ModelValueNode.ts';
-import type { AnyViolation, LeafNodeValidationState } from '../client/validation.ts';
-import { createValueState } from '../lib/reactivity/createValueState.ts';
+import { XPathNodeKindKey } from '@getodk/xpath';
+import type { ModelValueDefinition, ModelValueNode } from '../client/ModelValueNode.ts';
+import type { ValueType } from '../client/ValueType.ts';
+import type { XFormsXPathElement } from '../integration/xpath/adapter/XFormsXPathNode.ts';
+import type { RuntimeInputValue, RuntimeValue } from '../lib/codecs/getSharedValueCodec.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 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 { LeafNodeDefinition } from '../model/LeafNodeDefinition.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 { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
 import type { ValidationContext } from './internal-api/ValidationContext.ts';
-import type { ValueContext } from './internal-api/ValueContext.ts';
+import type { ClientReactiveSubmittableValueNode } from './internal-api/submission/ClientReactiveSubmittableValueNode.ts';
 
-export interface ModelValueDefinition extends LeafNodeDefinition {
-	readonly bodyElement: null;
-}
-
-interface ModelValueStateSpec extends DescendantNodeStateSpec<string> {
+interface ModelValueStateSpec<V extends ValueType> extends ValueNodeStateSpec<RuntimeValue<V>> {
 	readonly label: null;
 	readonly hint: null;
-	readonly children: null;
-	readonly value: SimpleAtomicState<string>;
-	readonly valueOptions: null;
 }
 
-export class ModelValue
-	extends DescendantNode<ModelValueDefinition, ModelValueStateSpec, null>
+export class ModelValue<V extends ValueType = ValueType>
+	extends ValueNode<V, ModelValueDefinition<V>, RuntimeValue<V>, RuntimeInputValue<V>>
 	implements
-		ModelValueNode,
+		ModelValueNode<V>,
+		XFormsXPathElement,
 		EvaluationContext,
-		SubscribableDependency,
 		ValidationContext,
-		ValueContext<string>
+		ClientReactiveSubmittableValueNode
 {
-	private readonly validation: SharedValidationState;
-	protected readonly state: SharedNodeState<ModelValueStateSpec>;
+	static from(parent: GeneralParentNode, definition: ModelValueDefinition): AnyModelValue;
+	static from<V extends ValueType>(
+		parent: GeneralParentNode,
+		definition: ModelValueDefinition<V>
+	): ModelValue<V> {
+		return new this(parent, definition);
+	}
+
+	// XFormsXPathElement
+	override readonly [XPathNodeKindKey] = 'element';
 
 	// InstanceNode
-	protected engineState: EngineState<ModelValueStateSpec>;
+	protected readonly state: SharedNodeState<ModelValueStateSpec<V>>;
+	protected readonly engineState: EngineState<ModelValueStateSpec<V>>;
 
 	// ModelValueNode
 	readonly nodeType = 'model-value';
 	readonly appearances = null;
-	readonly currentState: CurrentState<ModelValueStateSpec>;
+	readonly currentState: CurrentState<ModelValueStateSpec<V>>;
 
-	get validationState(): LeafNodeValidationState {
-		return this.validation.currentState;
-	}
-
-	// ValueContext
-	readonly encodeValue = identity<string>;
-	readonly decodeValue = identity<string>;
+	constructor(parent: GeneralParentNode, definition: ModelValueDefinition<V>) {
+		const codec = getSharedValueCodec(definition.valueType);
 
-	constructor(parent: GeneralParentNode, definition: ModelValueDefinition) {
-		super(parent, definition);
+		super(parent, definition, codec);
 
 		const sharedStateOptions = {
 			clientStateFactory: this.engineConfig.stateFactory,
@@ -77,7 +69,8 @@ export class ModelValue
 				hint: null,
 				children: null,
 				valueOptions: null,
-				value: createValueState(this),
+				value: this.valueState,
+				instanceValue: this.getInstanceValue,
 			},
 			sharedStateOptions
 		);
@@ -85,20 +78,20 @@ export class ModelValue
 		this.state = state;
 		this.engineState = state.engineState;
 		this.currentState = state.currentState;
-		this.validation = createValidationState(this, sharedStateOptions);
-	}
-
-	getViolation(): AnyViolation | null {
-		return this.validation.engineState.violation;
-	}
-
-	// ValidationContext
-	isBlank(): boolean {
-		return this.engineState.value === '';
-	}
-
-	// InstanceNode
-	getChildren(): readonly [] {
-		return [];
 	}
 }
+
+export type AnyModelValue =
+	| ModelValue<'barcode'>
+	| ModelValue<'binary'>
+	| ModelValue<'boolean'>
+	| ModelValue<'date'>
+	| ModelValue<'dateTime'>
+	| ModelValue<'decimal'>
+	| ModelValue<'geopoint'>
+	| ModelValue<'geoshape'>
+	| ModelValue<'geotrace'>
+	| ModelValue<'int'>
+	| ModelValue<'intent'>
+	| ModelValue<'string'>
+	| ModelValue<'time'>;

package/src/instance/Note.ts

@@ -1,9 +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 { TextRange } from '../client/TextRange.ts';
 import type { AnyViolation, LeafNodeValidationState } from '../client/validation.ts';
+import type { XFormsXPathElement } from '../integration/xpath/adapter/XFormsXPathNode.ts';
+import { createLeafNodeSubmissionState } from '../lib/client-reactivity/submission/createLeafNodeSubmissionState.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';
@@ -16,12 +20,12 @@ import { createNoteText, type ComputedNoteText } from '../lib/reactivity/text/cr
 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/NoteNodeDefinition.ts';
+import type { NoteNodeDefinition } from '../parse/model/NoteNodeDefinition.ts';
 import type { DescendantNodeStateSpec } from './abstract/DescendantNode.ts';
 import { DescendantNode } from './abstract/DescendantNode.ts';
 import type { GeneralParentNode } from './hierarchy.ts';
 import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
-import type { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
+import type { ClientReactiveSubmittableLeafNode } from './internal-api/submission/ClientReactiveSubmittableLeafNode.ts';
 import type { ValidationContext } from './internal-api/ValidationContext.ts';
 import type { ValueContext } from './internal-api/ValueContext.ts';
 
@@ -36,19 +40,23 @@ interface NoteStateSpec extends DescendantNodeStateSpec<string> {
 }
 
 export class Note
-	extends DescendantNode<NoteNodeDefinition, NoteStateSpec, null>
+	extends DescendantNode<NoteNodeDefinition, NoteStateSpec, GeneralParentNode, null>
 	implements
 		NoteNode,
+		XFormsXPathElement,
 		EvaluationContext,
-		SubscribableDependency,
 		ValidationContext,
-		ValueContext<string>
+		ValueContext<string>,
+		ClientReactiveSubmittableLeafNode<string>
 {
 	private readonly validation: SharedValidationState;
-	protected readonly state: SharedNodeState<NoteStateSpec>;
+
+	// XFormsXPathElement
+	override readonly [XPathNodeKindKey] = 'element';
 
 	// InstanceNode
-	protected engineState: EngineState<NoteStateSpec>;
+	protected readonly state: SharedNodeState<NoteStateSpec>;
+	protected readonly engineState: EngineState<NoteStateSpec>;
 
 	// NoteNode
 	readonly nodeType = 'note';
@@ -59,9 +67,11 @@ export class Note
 		return this.validation.currentState;
 	}
 
+	readonly submissionState: SubmissionState;
+
 	// ValueContext
+	override readonly contextNode = this;
 	readonly encodeValue = identity<string>;
-
 	readonly decodeValue = identity<string>;
 
 	constructor(parent: GeneralParentNode, definition: NoteNodeDefinition) {
@@ -73,7 +83,7 @@ export class Note
 			clientStateFactory: this.engineConfig.stateFactory,
 		};
 
-		const isReadonly = createNoteReadonlyThunk(this, definition.bind.readonly);
+		const isReadonly = createNoteReadonlyThunk(this, definition);
 		const noteTextComputation = createNoteText(this, definition.noteTextDefinition);
 
 		let noteText: ComputedNoteText;
@@ -124,13 +134,19 @@ export class Note
 		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;
 	}
 
-	// ValidationContext
 	isBlank(): boolean {
 		return this.engineState.value === '';
 	}