@getodk/xforms-engine 0.4.0 → 0.5.0

package/src/instance/Root.ts

@@ -1,9 +1,18 @@
-import type { XFormsXPathEvaluator } from '@getodk/xpath';
-import type { Accessor, Signal } from 'solid-js';
-import { createSignal } from 'solid-js';
+import { XPathNodeKindKey } from '@getodk/xpath';
+import type { Accessor } from 'solid-js';
 import type { ActiveLanguage, FormLanguage, FormLanguages } from '../client/FormLanguage.ts';
+import type { FormNodeID } from '../client/identity.ts';
 import type { RootNode } from '../client/RootNode.ts';
+import type { SubmissionDefinition } from '../client/submission/SubmissionDefinition.ts';
+import type {
+	SubmissionChunkedType,
+	SubmissionOptions,
+} from '../client/submission/SubmissionOptions.ts';
+import type { SubmissionResult } from '../client/submission/SubmissionResult.ts';
+import type { SubmissionState } from '../client/submission/SubmissionState.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';
@@ -15,146 +24,87 @@ import { createSharedNodeState } from '../lib/reactivity/node-state/createShared
 import { createAggregatedViolations } from '../lib/reactivity/validation/createAggregatedViolations.ts';
 import type { BodyClassList } from '../parse/body/BodyDefinition.ts';
 import type { RootDefinition } from '../parse/model/RootDefinition.ts';
-import type { XFormDOM } from '../parse/XFormDOM.ts';
-import { InstanceNode } from './abstract/InstanceNode.ts';
+import { DescendantNode } from './abstract/DescendantNode.ts';
 import { buildChildren } from './children.ts';
 import type { GeneralChildNode } from './hierarchy.ts';
-import type { NodeID } from './identity.ts';
-import type { EvaluationContext, EvaluationContextRoot } from './internal-api/EvaluationContext.ts';
-import type { InstanceConfig } from './internal-api/InstanceConfig.ts';
-import type { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
+import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
+import type { ClientReactiveSubmittableParentNode } from './internal-api/submission/ClientReactiveSubmittableParentNode.ts';
 import type { TranslationContext } from './internal-api/TranslationContext.ts';
+import type { PrimaryInstance } from './PrimaryInstance.ts';
 
 interface RootStateSpec {
-	readonly reference: string;
-	readonly readonly: boolean;
-	readonly relevant: boolean;
-	readonly required: boolean;
+	readonly reference: Accessor<string>;
+	readonly readonly: Accessor<boolean>;
+	readonly relevant: Accessor<boolean>;
+	readonly required: Accessor<boolean>;
 	readonly label: null;
 	readonly hint: null;
-	readonly children: Accessor<readonly NodeID[]>;
+	readonly children: Accessor<readonly FormNodeID[]>;
 	readonly valueOptions: null;
 	readonly value: null;
 
 	// Root-specific
-	readonly activeLanguage: Signal<ActiveLanguage>;
+	readonly activeLanguage: Accessor<ActiveLanguage>;
 }
 
-// Subset of types expected from evaluator
-interface ItextTranslations {
-	getActiveLanguage(): string | null;
-	getLanguages(): readonly string[];
-}
-
-interface InitialLanguageState {
-	readonly defaultLanguage: ActiveLanguage;
-	readonly languages: FormLanguages;
-}
-
-// TODO: it's really very silly that the XPath evaluator is the current
-// definitional source of truth for translation stuff... even though it currently makes sense that that's where it's first derived.
-const getInitialLanguageState = (translations: ItextTranslations): InitialLanguageState => {
-	const activeLanguageName = translations.getActiveLanguage();
-
-	if (activeLanguageName == null) {
-		const defaultLanguage: ActiveLanguage = {
-			isSyntheticDefault: true,
-			language: '',
-		};
-		const languages = [defaultLanguage] satisfies FormLanguages;
-
-		return {
-			defaultLanguage,
-			languages,
-		};
-	}
-
-	const languageNames = translations.getLanguages();
-
-	const inactiveLanguages = languageNames
-		.filter((languageName) => {
-			return languageName !== activeLanguageName;
-		})
-		.map((language): FormLanguage => {
-			return { language };
-		});
-
-	const languages = [
-		{ language: activeLanguageName } satisfies FormLanguage,
-
-		...inactiveLanguages,
-	] satisfies FormLanguages;
-	const [defaultLanguage] = languages;
-
-	return {
-		defaultLanguage,
-		languages,
-	};
-};
-
 export class Root
-	extends InstanceNode<RootDefinition, RootStateSpec, GeneralChildNode>
+	extends DescendantNode<RootDefinition, RootStateSpec, PrimaryInstance, GeneralChildNode>
 	implements
 		RootNode,
+		XFormsXPathElement,
 		EvaluationContext,
-		EvaluationContextRoot,
-		SubscribableDependency,
-		TranslationContext
+		TranslationContext,
+		ClientReactiveSubmittableParentNode<GeneralChildNode>
 {
 	private readonly childrenState: ChildrenState<GeneralChildNode>;
 
-	// InstanceNode
-	readonly hasReadonlyAncestor = () => false;
-	readonly isReadonly = () => false;
-	readonly hasNonRelevantAncestor = () => false;
-	readonly isRelevant = () => true;
+	// XFormsXPathElement
+	override readonly [XPathNodeKindKey] = 'element';
+
+	// DescendantNode
 	protected readonly state: SharedNodeState<RootStateSpec>;
 	protected readonly engineState: EngineState<RootStateSpec>;
 
+	override readonly hasReadonlyAncestor = () => false;
+	override readonly isSelfReadonly = () => false;
+	override readonly isReadonly = () => false;
+	override readonly hasNonRelevantAncestor = () => false;
+	override readonly isSelfRelevant = () => true;
+	override readonly isRelevant = () => true;
+	override readonly isRequired = () => false;
+
 	// RootNode
 	readonly nodeType = 'root';
 	readonly appearances = null;
 	readonly classes: BodyClassList;
 	readonly currentState: MaterializedChildren<CurrentState<RootStateSpec>, GeneralChildNode>;
 	readonly validationState: AncestorNodeValidationState;
+	readonly submissionState: SubmissionState;
 
-	protected readonly instanceDOM: XFormDOM;
-
-	// BaseNode
-	readonly root = this;
-
-	// EvaluationContext
-	readonly evaluator: XFormsXPathEvaluator;
-
-	readonly contextNode: Element;
+	// ClientReactiveSubmittableInstance
+	get submissionDefinition(): SubmissionDefinition {
+		return this.definition.submission;
+	}
 
 	// RootNode
-	override readonly parent = null;
-
 	readonly languages: FormLanguages;
 
-	// TranslationContext
-	get activeLanguage(): ActiveLanguage {
-		return this.engineState.activeLanguage;
-	}
-
-	constructor(xformDOM: XFormDOM, definition: RootDefinition, engineConfig: InstanceConfig) {
-		const reference = definition.nodeset;
+	constructor(parent: PrimaryInstance) {
+		const { definition } = parent;
+		const { nodeset: reference } = definition;
+		const computeReference: Accessor<string> = () => reference;
 
-		super(engineConfig, null, definition, {
-			computeReference: () => reference,
+		super(parent, definition, {
+			computeReference,
 		});
 
-		this.classes = definition.classes;
+		this.classes = parent.classes;
 
 		const childrenState = createChildrenState<Root, GeneralChildNode>(this);
 
 		this.childrenState = childrenState;
+		this.languages = parent.languages;
 
-		const instanceDOM = xformDOM.createInstance();
-		const evaluator = instanceDOM.primaryInstanceEvaluator;
-		const { translations } = evaluator;
-		const { defaultLanguage, languages } = getInitialLanguageState(translations);
 		const sharedStateOptions = {
 			clientStateFactory: this.engineConfig.stateFactory,
 		};
@@ -162,13 +112,13 @@ export class Root
 		const state = createSharedNodeState(
 			this.scope,
 			{
-				activeLanguage: createSignal<ActiveLanguage>(defaultLanguage),
-				reference,
+				activeLanguage: parent.getActiveLanguage,
+				reference: computeReference,
 				label: null,
 				hint: null,
-				readonly: false,
-				relevant: true,
-				required: false,
+				readonly: () => false,
+				relevant: () => true,
+				required: () => false,
 				valueOptions: null,
 				value: null,
 				children: childrenState.childIds,
@@ -184,17 +134,9 @@ export class Root
 			childrenState
 		);
 
-		const contextNode = instanceDOM.xformDocument.createElement(definition.nodeName);
-
-		instanceDOM.primaryInstanceRoot.replaceWith(contextNode);
-
-		this.evaluator = evaluator;
-		this.contextNode = contextNode;
-		this.instanceDOM = instanceDOM;
-		this.languages = languages;
-
 		childrenState.setChildren(buildChildren(this));
 		this.validationState = createAggregatedViolations(this, sharedStateOptions);
+		this.submissionState = createParentNodeSubmissionState(this);
 	}
 
 	getChildren(): readonly GeneralChildNode[] {
@@ -203,28 +145,14 @@ export class Root
 
 	// RootNode
 	setLanguage(language: FormLanguage): Root {
-		const activeLanguage = this.languages.find((formLanguage) => {
-			return formLanguage.language === language.language;
-		});
-
-		if (activeLanguage == null) {
-			throw new Error(`Language "${language.language}" not available`);
-		}
-
-		this.evaluator.translations.setActiveLanguage(activeLanguage.language);
-		this.state.setProperty('activeLanguage', activeLanguage);
+		this.rootDocument.setLanguage(language);
 
 		return this;
 	}
 
-	// SubscribableDependency
-	override subscribe(): void {
-		super.subscribe();
-
-		// TODO: typescript-eslint is right to object to this! We should _at least_
-		// make internal reactive reads obvious, i.e. function calls.
-		//
-		// eslint-disable-next-line @typescript-eslint/no-unused-expressions -- read == subscribe
-		this.engineState.activeLanguage;
+	prepareSubmission<ChunkedType extends SubmissionChunkedType = 'monolithic'>(
+		options?: SubmissionOptions<ChunkedType>
+	): Promise<SubmissionResult<ChunkedType>> {
+		return this.rootDocument.prepareSubmission(options);
 	}
 }

package/src/instance/SelectField.ts

@@ -1,9 +1,13 @@
 import { xmlXPathWhitespaceSeparatedList } from '@getodk/common/lib/string/whitespace.ts';
+import { XPathNodeKindKey } from '@getodk/xpath';
 import type { Accessor } from 'solid-js';
-import { untrack } from 'solid-js';
+import { createMemo, untrack } from 'solid-js';
 import type { SelectItem, SelectNode, SelectNodeAppearances } from '../client/SelectNode.ts';
 import type { TextRange } from '../client/TextRange.ts';
+import type { SubmissionState } from '../client/submission/SubmissionState.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 { createSelectItems } from '../lib/reactivity/createSelectItems.ts';
 import { createValueState } from '../lib/reactivity/createValueState.ts';
 import type { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
@@ -22,9 +26,9 @@ 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 { ValidationContext } from './internal-api/ValidationContext.ts';
 import type { ValueContext } from './internal-api/ValueContext.ts';
+import type { ClientReactiveSubmittableLeafNode } from './internal-api/submission/ClientReactiveSubmittableLeafNode.ts';
 
 export interface SelectFieldDefinition extends LeafNodeDefinition {
 	readonly bodyElement: AnySelectDefinition;
@@ -39,17 +43,21 @@ interface SelectFieldStateSpec extends DescendantNodeStateSpec<readonly SelectIt
 }
 
 export class SelectField
-	extends DescendantNode<SelectFieldDefinition, SelectFieldStateSpec, null>
+	extends DescendantNode<SelectFieldDefinition, SelectFieldStateSpec, GeneralParentNode, null>
 	implements
 		SelectNode,
+		XFormsXPathElement,
 		EvaluationContext,
-		SubscribableDependency,
 		ValidationContext,
-		ValueContext<readonly SelectItem[]>
+		ValueContext<readonly SelectItem[]>,
+		ClientReactiveSubmittableLeafNode<readonly SelectItem[]>
 {
 	private readonly selectExclusive: boolean;
 	private readonly validation: SharedValidationState;
 
+	// XFormsXPathElement
+	override readonly [XPathNodeKindKey] = 'element';
+
 	// InstanceNode
 	protected readonly state: SharedNodeState<SelectFieldStateSpec>;
 	protected override engineState: EngineState<SelectFieldStateSpec>;
@@ -63,32 +71,35 @@ export class SelectField
 		return this.validation.currentState;
 	}
 
+	readonly submissionState: SubmissionState;
+
 	// ValueContext
+	override readonly contextNode = this;
+
 	readonly encodeValue = (runtimeValue: readonly SelectItem[]): string => {
 		const itemValues = new Set(runtimeValue.map(({ value }) => value));
+		const selectedItems = this.getValueOptions().filter(({ value }) => {
+			return itemValues.has(value);
+		});
 
-		return Array.from(itemValues).join(' ');
+		return selectedItems.map(({ value }) => value).join(' ');
 	};
 
 	readonly decodeValue = (instanceValue: string): readonly SelectItem[] => {
-		return this.scope.runTask(() => {
-			const values = xmlXPathWhitespaceSeparatedList(instanceValue, {
+		const itemValues = new Set(
+			xmlXPathWhitespaceSeparatedList(instanceValue, {
 				ignoreEmpty: true,
-			});
-
-			const items = this.getSelectItemsByValue();
+			})
+		);
 
-			return values
-				.map((value) => {
-					return items.get(value);
-				})
-				.filter((item): item is SelectItem => {
-					return item != null;
-				});
+		// TODO: also want set-like behavior, probably?
+		return this.getValueOptions().filter((option) => {
+			return itemValues.has(option.value);
 		});
 	};
 
 	protected readonly getValueOptions: Accessor<readonly SelectItem[]>;
+	protected readonly getValue: Accessor<readonly SelectItem[]>;
 
 	constructor(parent: GeneralParentNode, definition: SelectFieldDefinition) {
 		super(parent, definition);
@@ -100,6 +111,26 @@ export class SelectField
 
 		this.getValueOptions = valueOptions;
 
+		const [baseGetValue, setValue] = createValueState(this);
+
+		const getValue = this.scope.runTask(() => {
+			const selectItemsByValue = createMemo((): ReadonlyMap<string, SelectItem> => {
+				return new Map(valueOptions().map((item) => [item.value, item]));
+			});
+
+			return createMemo(() => {
+				const items = selectItemsByValue();
+
+				return baseGetValue().filter((item) => {
+					return items.has(item.value);
+				});
+			});
+		});
+
+		this.getValue = getValue;
+
+		const valueState: SimpleAtomicState<readonly SelectItem[]> = [getValue, setValue];
+
 		const sharedStateOptions = {
 			clientStateFactory: this.engineConfig.stateFactory,
 		};
@@ -115,7 +146,7 @@ export class SelectField
 				label: createNodeLabel(this, definition),
 				hint: createFieldHint(this, definition),
 				children: null,
-				value: createValueState(this),
+				value: valueState,
 				valueOptions,
 			},
 			sharedStateOptions
@@ -125,6 +156,7 @@ export class SelectField
 		this.engineState = state.engineState;
 		this.currentState = state.currentState;
 		this.validation = createValidationState(this, sharedStateOptions);
+		this.submissionState = createLeafNodeSubmissionState(this);
 	}
 
 	protected getSelectItemsByValue(
@@ -163,6 +195,11 @@ export class SelectField
 		this.updateSelectedItemValues([value]);
 	}
 
+	// XFormsXPathElement
+	override getXPathValue(): string {
+		return this.encodeValue(this.engineState.value);
+	}
+
 	// SelectNode
 	select(selectedItem: SelectItem): Root {
 		const { engineState, root } = this;

package/src/instance/Subtree.ts

@@ -1,6 +1,11 @@
-import { type Accessor } from 'solid-js';
+import { XPathNodeKindKey } from '@getodk/xpath';
+import type { Accessor } from 'solid-js';
+import type { FormNodeID } from '../client/identity.ts';
+import type { SubmissionState } from '../client/submission/SubmissionState.ts';
 import type { SubtreeDefinition, SubtreeNode } from '../client/SubtreeNode.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';
@@ -14,33 +19,39 @@ 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';
 
 interface SubtreeStateSpec extends DescendantNodeSharedStateSpec {
 	readonly label: null;
 	readonly hint: null;
-	readonly children: Accessor<readonly NodeID[]>;
+	readonly children: Accessor<readonly FormNodeID[]>;
 	readonly valueOptions: null;
 	readonly value: null;
 }
 
 export class Subtree
-	extends DescendantNode<SubtreeDefinition, SubtreeStateSpec, GeneralChildNode>
-	implements SubtreeNode, EvaluationContext, SubscribableDependency
+	extends DescendantNode<SubtreeDefinition, SubtreeStateSpec, GeneralParentNode, GeneralChildNode>
+	implements
+		SubtreeNode,
+		XFormsXPathElement,
+		EvaluationContext,
+		ClientReactiveSubmittableParentNode<GeneralChildNode>
 {
 	private readonly childrenState: ChildrenState<GeneralChildNode>;
 
+	override readonly [XPathNodeKindKey] = 'element';
+
 	// InstanceNode
 	protected readonly state: SharedNodeState<SubtreeStateSpec>;
-	protected engineState: EngineState<SubtreeStateSpec>;
+	protected readonly engineState: EngineState<SubtreeStateSpec>;
 
 	// SubtreeNode
 	readonly nodeType = 'subtree';
 	readonly appearances = null;
 	readonly currentState: MaterializedChildren<CurrentState<SubtreeStateSpec>, GeneralChildNode>;
 	readonly validationState: AncestorNodeValidationState;
+	readonly submissionState: SubmissionState;
 
 	constructor(parent: GeneralParentNode, definition: SubtreeDefinition) {
 		super(parent, definition);
@@ -80,6 +91,7 @@ export class Subtree
 
 		childrenState.setChildren(buildChildren(this));
 		this.validationState = createAggregatedViolations(this, sharedStateOptions);
+		this.submissionState = createParentNodeSubmissionState(this);
 	}
 
 	getChildren(): readonly GeneralChildNode[] {

package/src/instance/TriggerControl.ts

@@ -1,7 +1,11 @@
+import { XPathNodeKindKey } from '@getodk/xpath';
 import type { Accessor } from 'solid-js';
 import type { TextRange } from '../client/TextRange.ts';
 import type { TriggerNode, TriggerNodeDefinition } from '../client/TriggerNode.ts';
+import type { SubmissionState } from '../client/submission/SubmissionState.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 { 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';
@@ -18,9 +22,9 @@ 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 { ValidationContext } from './internal-api/ValidationContext.ts';
 import type { ValueContext } from './internal-api/ValueContext.ts';
+import type { ClientReactiveSubmittableLeafNode } from './internal-api/submission/ClientReactiveSubmittableLeafNode.ts';
 
 interface TriggerControlStateSpec extends DescendantNodeStateSpec<boolean> {
 	readonly label: Accessor<TextRange<'label'> | null>;
@@ -33,19 +37,23 @@ interface TriggerControlStateSpec extends DescendantNodeStateSpec<boolean> {
 const TRIGGER_ASSIGNED_VALUE = 'OK';
 
 export class TriggerControl
-	extends DescendantNode<TriggerNodeDefinition, TriggerControlStateSpec, null>
+	extends DescendantNode<TriggerNodeDefinition, TriggerControlStateSpec, GeneralParentNode, null>
 	implements
 		TriggerNode,
+		XFormsXPathElement,
 		EvaluationContext,
-		SubscribableDependency,
 		ValidationContext,
-		ValueContext<boolean>
+		ValueContext<boolean>,
+		ClientReactiveSubmittableLeafNode<boolean>
 {
 	private readonly validation: SharedValidationState;
-	protected readonly state: SharedNodeState<TriggerControlStateSpec>;
+
+	// XFormsXPathElement
+	override readonly [XPathNodeKindKey] = 'element';
 
 	// InstanceNode
-	protected engineState: EngineState<TriggerControlStateSpec>;
+	protected readonly state: SharedNodeState<TriggerControlStateSpec>;
+	protected readonly engineState: EngineState<TriggerControlStateSpec>;
 
 	// TriggerNode
 	readonly nodeType = 'trigger';
@@ -56,7 +64,10 @@ export class TriggerControl
 		return this.validation.currentState;
 	}
 
+	readonly submissionState: SubmissionState;
+
 	// ValueContext
+	override readonly contextNode = this;
 	readonly encodeValue: (runtimeValue: boolean) => string;
 	readonly decodeValue: (instanceValue: string) => boolean;
 
@@ -109,6 +120,12 @@ export class TriggerControl
 		this.engineState = state.engineState;
 		this.currentState = state.currentState;
 		this.validation = createValidationState(this, sharedStateOptions);
+		this.submissionState = createLeafNodeSubmissionState(this);
+	}
+
+	// XFormsXPathElement
+	override getXPathValue(): string {
+		return this.encodeValue(this.engineState.value);
 	}
 
 	// ValidationContext