@getodk/xforms-engine 0.4.0 → 0.6.0

package/src/instance/abstract/InstanceNode.ts

@@ -1,10 +1,18 @@
-import type { XFormsXPathEvaluator } from '@getodk/xpath';
+import type { XPathNodeKindKey } from '@getodk/xpath';
 import type { Accessor, Signal } from 'solid-js';
 import type { BaseNode } from '../../client/BaseNode.ts';
 import type { NodeAppearances } from '../../client/NodeAppearances.ts';
-import type { InstanceNodeType } from '../../client/node-types.ts';
+import type { FormNodeID } from '../../client/identity.ts';
+import type { InstanceNodeType as ClientInstanceNodeType } from '../../client/node-types.ts';
+import type { SubmissionState } from '../../client/submission/SubmissionState.ts';
 import type { NodeValidationState } from '../../client/validation.ts';
-import type { TextRange } from '../../index.ts';
+import type { ActiveLanguage, TextRange } from '../../index.ts';
+import type { EngineXPathEvaluator } from '../../integration/xpath/EngineXPathEvaluator.ts';
+import type {
+	XFormsXPathPrimaryInstanceNode,
+	XFormsXPathPrimaryInstanceNodeKind,
+} from '../../integration/xpath/adapter/XFormsXPathNode.ts';
+import type { PrimaryInstanceXPathNode } from '../../integration/xpath/adapter/kind.ts';
 import type { MaterializedChildren } from '../../lib/reactivity/materializeCurrentStateChildren.ts';
 import type { CurrentState } from '../../lib/reactivity/node-state/createCurrentState.ts';
 import type { EngineState } from '../../lib/reactivity/node-state/createEngineState.ts';
@@ -13,13 +21,24 @@ import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
 import { createReactiveScope } from '../../lib/reactivity/scope.ts';
 import type { SimpleAtomicState } from '../../lib/reactivity/types.ts';
 import type { AnyNodeDefinition } from '../../parse/model/NodeDefinition.ts';
+import type { PrimaryInstance } from '../PrimaryInstance.ts';
 import type { Root } from '../Root.ts';
 import type { AnyChildNode, AnyNode, AnyParentNode } from '../hierarchy.ts';
-import type { NodeID } from '../identity.ts';
-import { declareNodeID } from '../identity.ts';
+import { nodeID } from '../identity.ts';
 import type { EvaluationContext } from '../internal-api/EvaluationContext.ts';
 import type { InstanceConfig } from '../internal-api/InstanceConfig.ts';
-import type { SubscribableDependency } from '../internal-api/SubscribableDependency.ts';
+
+export type EngineInstanceNodeType = ClientInstanceNodeType | 'primary-instance';
+
+export interface BaseEngineNode extends Omit<BaseNode, 'nodeType'> {
+	readonly nodeType: EngineInstanceNodeType;
+}
+
+// prettier-ignore
+export type InstanceNodeValueOptionsStateSpec =
+	| Accessor<null>
+	| Accessor<readonly unknown[]>
+	| null
 
 export interface InstanceNodeStateSpec<Value = never> {
 	readonly reference: Accessor<string> | string;
@@ -28,8 +47,8 @@ export interface InstanceNodeStateSpec<Value = never> {
 	readonly required: Accessor<boolean> | boolean;
 	readonly label: Accessor<TextRange<'label'> | null> | null;
 	readonly hint: Accessor<TextRange<'hint'> | null> | null;
-	readonly children: Accessor<readonly NodeID[]> | null;
-	readonly valueOptions: Accessor<null> | Accessor<readonly unknown[]> | null;
+	readonly children: Accessor<readonly FormNodeID[]> | null;
+	readonly valueOptions: InstanceNodeValueOptionsStateSpec;
 	readonly value: Signal<Value> | SimpleAtomicState<Value> | null;
 }
 
@@ -71,19 +90,26 @@ type ComputeInstanceNodeReference = <This extends ComputableReferenceNode>(
 
 export interface InstanceNodeOptions {
 	readonly computeReference?: () => string;
+	readonly scope?: ReactiveScope;
 }
 
 export abstract class InstanceNode<
 		Definition extends AnyNodeDefinition,
 		// eslint-disable-next-line @typescript-eslint/no-explicit-any
 		Spec extends InstanceNodeStateSpec<any>,
+		Parent extends AnyParentNode | null,
 		Child extends AnyChildNode | null = null,
 	>
-	implements BaseNode, EvaluationContext, SubscribableDependency
+	implements BaseEngineNode, XFormsXPathPrimaryInstanceNode, EvaluationContext
 {
 	protected abstract readonly state: SharedNodeState<Spec>;
 	protected abstract readonly engineState: EngineState<Spec>;
 
+	// XFormsXPathPrimaryInstanceNode
+	abstract readonly [XPathNodeKindKey]: XFormsXPathPrimaryInstanceNodeKind;
+	readonly rootDocument: PrimaryInstance;
+	abstract readonly root: Root;
+
 	/**
 	 * @package Exposed on every node type to facilitate inheritance, as well as
 	 * conditional behavior for value nodes.
@@ -109,26 +135,28 @@ export abstract class InstanceNode<
 	abstract readonly isRelevant: Accessor<boolean>;
 
 	// BaseNode: identity
-	readonly nodeId: NodeID;
+	readonly nodeId: FormNodeID;
 
 	// BaseNode: node types and variants (e.g. for narrowing)
-	abstract readonly nodeType: InstanceNodeType;
+	abstract readonly nodeType: EngineInstanceNodeType;
 
 	abstract readonly appearances: NodeAppearances<Definition>;
 
+	abstract readonly nodeOptions: object | null;
+
 	abstract readonly currentState: InstanceNodeCurrentState<Spec, Child>;
 
 	abstract readonly validationState: NodeValidationState;
 
-	// BaseNode: structural
-	abstract readonly root: Root;
+	abstract readonly submissionState: SubmissionState;
 
 	// EvaluationContext: instance-global/shared
-	abstract readonly evaluator: XFormsXPathEvaluator;
+	abstract readonly evaluator: EngineXPathEvaluator;
+	abstract readonly getActiveLanguage: Accessor<ActiveLanguage>;
 
-	// EvaluationContext *and* Subscribable: node-specific
+	// EvaluationContext: node-specific
+	abstract readonly isAttached: Accessor<boolean>;
 	readonly scope: ReactiveScope;
-
 	readonly computeReference: ComputeInstanceNodeReference;
 
 	protected readonly computeChildStepReference: ComputeInstanceNodeReference = (
@@ -141,7 +169,7 @@ export abstract class InstanceNode<
 			);
 		}
 
-		return `${parent.contextReference()}/${definition.nodeName}`;
+		return `${parent.contextReference()}/${definition.qualifiedName.getPrefixedName()}`;
 	};
 
 	// EvaluationContext: node-specific
@@ -149,114 +177,92 @@ export abstract class InstanceNode<
 		return this.computeReference(this.parent, this.definition);
 	};
 
-	abstract readonly contextNode: Element;
+	/**
+	 * Note: it is expected that at least some node subclasses will override this
+	 * to reflect (or in the case of intermediate abstract base classes, to
+	 * constrain) their more specific `this` type.
+	 */
+	readonly contextNode: PrimaryInstanceXPathNode =
+		this as AnyInstanceNode as PrimaryInstanceXPathNode;
 
 	constructor(
 		readonly engineConfig: InstanceConfig,
-		readonly parent: AnyParentNode | null,
+		readonly parent: Parent,
 		readonly definition: Definition,
 		options?: InstanceNodeOptions
 	) {
-		this.computeReference = options?.computeReference ?? this.computeChildStepReference;
-
-		this.scope = createReactiveScope();
-		this.engineConfig = engineConfig;
-		this.nodeId = declareNodeID(engineConfig.createUniqueId());
-		this.definition = definition;
-	}
+		const self = this as AnyInstanceNode as AnyNode;
 
-	/**
-	 * @package This presently serves a few internal use cases, where certain
-	 * behaviors depend on arbitrary traversal from any point in the instance
-	 * tree, without particular regard for the visited node type. It isn't
-	 * intended for external traversal or any other means of consuming children by
-	 * a client. This return type intentionally deviates from one structural
-	 * expectation, requiring even leaf nodes to return an array (though for those
-	 * nodes it will always be empty). This affords consistency and efficiency of
-	 * interface for those internal uses.
-	 */
-	abstract getChildren(this: AnyInstanceNode): readonly AnyChildNode[];
-
-	getNodesByReference(
-		this: AnyNode,
-		visited: WeakSet<AnyNode>,
-		dependencyReference: string
-	): readonly SubscribableDependency[] {
-		if (visited.has(this)) {
-			return [];
-		}
-
-		visited.add(this);
-
-		const { nodeset } = this.definition;
-
-		if (dependencyReference === nodeset) {
-			if (this.nodeType === 'repeat-instance') {
-				return [this.parent];
+		if (parent == null) {
+			if (!self.isPrimaryInstance()) {
+				throw new Error(
+					'Failed to construct node: not a primary instance, no parent node specified'
+				);
 			}
 
-			return [this];
+			this.rootDocument = self;
+		} else {
+			this.rootDocument = parent.rootDocument;
 		}
 
-		if (
-			dependencyReference.startsWith(`${nodeset}/`) ||
-			dependencyReference.startsWith(`${nodeset}[`)
-		) {
-			return this.getChildren().flatMap((child) => {
-				return child.getNodesByReference(visited, dependencyReference);
-			});
-		}
+		this.computeReference = options?.computeReference ?? this.computeChildStepReference;
 
-		return this.parent?.getNodesByReference(visited, dependencyReference) ?? [];
+		this.scope = options?.scope ?? createReactiveScope();
+		this.engineConfig = engineConfig;
+		this.nodeId = nodeID(engineConfig.createUniqueId());
+		this.definition = definition;
 	}
 
-	// EvaluationContext: node-relative
-	getSubscribableDependenciesByReference(
-		this: AnyNode,
-		reference: string
-	): readonly SubscribableDependency[] {
-		if (this.nodeType === 'root') {
-			const visited = new WeakSet<AnyNode>();
-
-			return this.getNodesByReference(visited, reference);
-		}
+	/** @package */
+	isPrimaryInstance(): this is PrimaryInstance {
+		return this.parent == null;
+	}
 
-		return this.root.getSubscribableDependenciesByReference(reference);
+	/** @package */
+	isRoot(): this is Root {
+		return this.parent?.nodeType === 'primary-instance';
 	}
 
-	// SubscribableDependency
 	/**
-	 * This is a default implementation suitable for most node types. The rest
-	 * (currently: `Root`, `RepeatRange`, `RepeatInstance`) should likely extend
-	 * this behavior, rather than simply overriding it.
+	 * @package This presently serves a growing variety of internal use cases,
+	 * where certain behaviors depend on arbitrary traversal from any point in the
+	 * instance tree, without particular regard for the visited node type. It
+	 * isn't intended for external traversal or any other means of consuming
+	 * children by a client. This return type intentionally deviates from one
+	 * structural expectation, requiring even leaf nodes to return an array
+	 * (though for those nodes it will always be empty). This affords consistency
+	 * and efficiency of interface for those internal uses.
+	 */
+	abstract getChildren(this: AnyInstanceNode): readonly AnyChildNode[];
+
+	// XFormsXPathNode
+	/**
+	 * @todo Values as text nodes(?)
 	 */
-	subscribe(): void {
-		const { engineState } = this;
-
-		// Note: a previous iteration of this default implementation guarded these
-		// reactive reads behind a relevance check. This caused timing issues for
-		// downstream computations referencing a node whose relevance changes.
-		//
-		// That original guard was intended to reduce excessive redundant
-		// computations, and so removing it is intended as a naive compromise of
-		// performance for obvious correctness improvements.
-		//
-		// This compromise, like many others, will be moot if/when we decide to
-		// decouple XPath evaluation from the browser/XML DOM: reactive
-		// subscriptions would be established by evaluation of the expressions
-		// themselves (as they traverse instance state and access values), rather
-		// than this safer/less focused approach.
-
-		// TODO: typescript-eslint is right to object to these! We should _at least_
-		// make internal reactive reads obvious, i.e. function calls.
-
-		// eslint-disable-next-line @typescript-eslint/no-unused-expressions
-		engineState.reference;
-		// eslint-disable-next-line @typescript-eslint/no-unused-expressions
-		engineState.relevant;
-		// eslint-disable-next-line @typescript-eslint/no-unused-expressions
-		engineState.children;
-		// eslint-disable-next-line @typescript-eslint/no-unused-expressions
-		engineState.value;
+	getXPathChildNodes(): readonly AnyChildNode[] {
+		return (this as AnyInstanceNode).getChildren().flatMap((child) => {
+			switch (child.nodeType) {
+				case 'repeat-range:controlled':
+				case 'repeat-range:uncontrolled': {
+					const repeatInstances = child.getXPathChildNodes();
+
+					if (repeatInstances.length > 0) {
+						return repeatInstances;
+					}
+
+					return child;
+				}
+
+				default:
+					return child;
+			}
+		});
+	}
+
+	getXPathValue(): string {
+		return (this as AnyInstanceNode as AnyNode)
+			.getXPathChildNodes()
+			.map((child) => child.getXPathValue())
+			.join('');
 	}
 }

package/src/instance/abstract/UnsupportedControl.ts

@@ -1,6 +1,8 @@
 import { identity } from '@getodk/common/lib/identity.ts';
+import { XPathNodeKindKey } from '@getodk/xpath';
 import type { Accessor } from 'solid-js';
 import type { UnsupportedControlNodeType } from '../../client/node-types.ts';
+import type { SubmissionState } from '../../client/submission/SubmissionState.ts';
 import type { TextRange } from '../../client/TextRange.ts';
 import type {
 	UnsupportedControlDefinition,
@@ -8,6 +10,8 @@ import type {
 	UnsupportedControlNode,
 } from '../../client/unsupported/UnsupportedControlNode.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';
@@ -23,9 +27,9 @@ import {
 	type SharedValidationState,
 } from '../../lib/reactivity/validation/createValidation.ts';
 import type { UnknownAppearanceDefinition } from '../../parse/body/appearance/unknownAppearanceParser.ts';
-import type { GeneralParentNode } from '../hierarchy.ts';
+import type { AnyUnsupportedControl, 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';
 import { DescendantNode, type DescendantNodeStateSpec } from './DescendantNode.ts';
@@ -61,17 +65,26 @@ class UnsupportedControlWriteError extends Error {
 }
 
 export abstract class UnsupportedControl<Type extends UnsupportedControlNodeType>
-	extends DescendantNode<TypedUnsupportedControlDefinition<Type>, UnsupportedControlStateSpec, null>
+	extends DescendantNode<
+		TypedUnsupportedControlDefinition<Type>,
+		UnsupportedControlStateSpec,
+		GeneralParentNode,
+		null
+	>
 	implements
 		UnsupportedControlNode,
+		XFormsXPathElement,
 		EvaluationContext,
-		SubscribableDependency,
 		ValidationContext,
-		ValueContext<unknown>
+		ValueContext<unknown>,
+		ClientReactiveSubmittableLeafNode<unknown>
 {
 	private readonly validation: SharedValidationState;
 	protected readonly state: SharedNodeState<UnsupportedControlStateSpec>;
 
+	// XFormsXPathElement
+	override readonly [XPathNodeKindKey] = 'element';
+
 	// InstanceNode
 	protected readonly engineState: EngineState<UnsupportedControlStateSpec>;
 
@@ -79,13 +92,18 @@ export abstract class UnsupportedControl<Type extends UnsupportedControlNodeType
 	abstract override readonly nodeType: Type;
 
 	readonly appearances: UnknownAppearanceDefinition;
+	readonly nodeOptions = null;
 	readonly currentState: CurrentState<UnsupportedControlStateSpec>;
 
 	get validationState(): LeafNodeValidationState {
 		return this.validation.currentState;
 	}
 
+	readonly submissionState: SubmissionState;
+
 	// ValueContext
+	abstract override readonly contextNode: AnyUnsupportedControl & this;
+
 	readonly encodeValue = (instanceValue: unknown): string => {
 		const encoded = instanceValue;
 
@@ -128,6 +146,12 @@ export abstract class UnsupportedControl<Type extends UnsupportedControlNodeType
 		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

package/src/instance/abstract/ValueNode.ts

@@ -0,0 +1,128 @@
+import { XPathNodeKindKey } from '@getodk/xpath';
+import type { Accessor } from 'solid-js';
+import type { BaseValueNode } from '../../client/BaseValueNode.ts';
+import type { LeafNodeType as ValueNodeType } from '../../client/node-types.ts';
+import type { SubmissionState } from '../../client/submission/SubmissionState.ts';
+import type { AnyViolation, LeafNodeValidationState } from '../../client/validation.ts';
+import type { ValueType } from '../../client/ValueType.ts';
+import type { XFormsXPathElement } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
+import { createValueNodeSubmissionState } from '../../lib/client-reactivity/submission/createValueNodeSubmissionState.ts';
+import type {
+	RuntimeValueSetter,
+	RuntimeValueState,
+	ValueCodec,
+} from '../../lib/codecs/ValueCodec.ts';
+import { createInstanceValueState } from '../../lib/reactivity/createInstanceValueState.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 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 { LeafNodeDefinition } from '../../parse/model/LeafNodeDefinition.ts';
+import type { GeneralParentNode } from '../hierarchy.ts';
+import type { EvaluationContext } from '../internal-api/EvaluationContext.ts';
+import type {
+	DecodeInstanceValue,
+	InstanceValueContext,
+} from '../internal-api/InstanceValueContext.ts';
+import type { ClientReactiveSubmittableValueNode } from '../internal-api/submission/ClientReactiveSubmittableValueNode.ts';
+import type { ValidationContext } from '../internal-api/ValidationContext.ts';
+import type { DescendantNodeStateSpec } from './DescendantNode.ts';
+import { DescendantNode } from './DescendantNode.ts';
+
+export type ValueNodeDefinition<V extends ValueType> = LeafNodeDefinition<V>;
+
+export interface ValueNodeStateSpec<RuntimeValue> extends DescendantNodeStateSpec<RuntimeValue> {
+	readonly children: null;
+	readonly value: SimpleAtomicState<RuntimeValue>;
+	readonly instanceValue: Accessor<string>;
+}
+
+export abstract class ValueNode<
+		V extends ValueType,
+		Definition extends ValueNodeDefinition<V>,
+		RuntimeValue extends RuntimeInputValue,
+		RuntimeInputValue = RuntimeValue,
+	>
+	extends DescendantNode<Definition, ValueNodeStateSpec<RuntimeValue>, GeneralParentNode, null>
+	implements
+		BaseValueNode<V, RuntimeValue>,
+		XFormsXPathElement,
+		EvaluationContext,
+		InstanceValueContext,
+		ValidationContext,
+		ClientReactiveSubmittableValueNode
+{
+	protected readonly validation: SharedValidationState;
+	protected readonly getInstanceValue: Accessor<string>;
+	protected readonly valueState: RuntimeValueState<RuntimeValue>;
+	protected readonly setValueState: RuntimeValueSetter<RuntimeInputValue>;
+
+	// XFormsXPathElement
+	override readonly [XPathNodeKindKey] = 'element';
+	override readonly getXPathValue: () => string;
+
+	// InstanceNode
+	protected abstract override readonly state: SharedNodeState<ValueNodeStateSpec<RuntimeValue>>;
+	protected abstract override readonly engineState: EngineState<ValueNodeStateSpec<RuntimeValue>>;
+
+	// InstanceValueContext
+	readonly decodeInstanceValue: DecodeInstanceValue;
+
+	// BaseValueNode
+	abstract override readonly nodeType: ValueNodeType;
+	readonly valueType: V;
+
+	abstract override readonly currentState: CurrentState<ValueNodeStateSpec<RuntimeValue>>;
+
+	get validationState(): LeafNodeValidationState {
+		return this.validation.currentState;
+	}
+
+	readonly submissionState: SubmissionState;
+
+	constructor(
+		parent: GeneralParentNode,
+		definition: Definition,
+		codec: ValueCodec<V, RuntimeValue, RuntimeInputValue>
+	) {
+		super(parent, definition);
+
+		this.valueType = definition.valueType;
+		this.decodeInstanceValue = codec.decodeInstanceValue;
+
+		const instanceValueState = createInstanceValueState(this, {
+			initialValueSource: 'FORM_DEFAULT',
+		});
+		const valueState = codec.createRuntimeValueState(instanceValueState);
+
+		const [getInstanceValue] = instanceValueState;
+		const [, setValueState] = valueState;
+
+		this.getInstanceValue = getInstanceValue;
+		this.setValueState = setValueState;
+		this.getXPathValue = () => {
+			return this.getInstanceValue();
+		};
+		this.valueState = valueState;
+		this.validation = createValidationState(this, {
+			clientStateFactory: this.engineConfig.stateFactory,
+		});
+		this.submissionState = createValueNodeSubmissionState(this);
+	}
+
+	// ValidationContext
+	getViolation(): AnyViolation | null {
+		return this.validation.engineState.violation;
+	}
+
+	isBlank(): boolean {
+		return this.getInstanceValue() === '';
+	}
+
+	// InstanceNode
+	getChildren(): readonly [] {
+		return [];
+	}
+}