@getodk/xforms-engine 0.4.0 → 0.5.0

package/src/instance/abstract/DescendantNode.ts

@@ -1,15 +1,22 @@
-import type { XFormsXPathEvaluator } from '@getodk/xpath';
+import { XPathNodeKindKey } from '@getodk/xpath';
 import type { Accessor } from 'solid-js';
+import { createMemo } from 'solid-js';
 import type { BaseNode } from '../../client/BaseNode.ts';
+import type { ActiveLanguage } from '../../client/FormLanguage.ts';
+import type { InstanceNodeType } from '../../client/node-types.ts';
+import type { PrimaryInstanceXPathChildNode } from '../../integration/xpath/adapter/kind.ts';
+import type {
+	XFormsXPathPrimaryInstanceDescendantNode,
+	XFormsXPathPrimaryInstanceDescendantNodeKind,
+} from '../../integration/xpath/adapter/XFormsXPathNode.ts';
+import { XFORMS_XPATH_NODE_RANGE_KIND } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
+import type { EngineXPathEvaluator } from '../../integration/xpath/EngineXPathEvaluator.ts';
 import { createComputedExpression } from '../../lib/reactivity/createComputedExpression.ts';
 import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
 import type { AnyDescendantNodeDefinition } from '../../parse/model/DescendentNodeDefinition.ts';
-import type { LeafNodeDefinition } from '../../parse/model/LeafNodeDefinition.ts';
 import type { AnyNodeDefinition } from '../../parse/model/NodeDefinition.ts';
-import type { RepeatInstanceDefinition } from '../../parse/model/RepeatInstanceDefinition.ts';
-import type { AnyChildNode, GeneralParentNode, RepeatRange } from '../hierarchy.ts';
+import type { AnyChildNode, AnyParentNode, RepeatRange } from '../hierarchy.ts';
 import type { EvaluationContext } from '../internal-api/EvaluationContext.ts';
-import type { SubscribableDependency } from '../internal-api/SubscribableDependency.ts';
 import type { RepeatInstance } from '../repeat/RepeatInstance.ts';
 import type { Root } from '../Root.ts';
 import type { InstanceNodeStateSpec } from './InstanceNode.ts';
@@ -34,19 +41,13 @@ export type DescendantNodeDefinition = Extract<
 	AnyDescendantNodeDefinition
 >;
 
-// prettier-ignore
-export type DescendantNodeParent<Definition extends DescendantNodeDefinition> =
-	Definition extends LeafNodeDefinition
-		? GeneralParentNode
-	: Definition extends RepeatInstanceDefinition
-		? RepeatRange
-		: GeneralParentNode;
-
 export type AnyDescendantNode = DescendantNode<
 	DescendantNodeDefinition,
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	DescendantNodeStateSpec<any>,
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	any,
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	any
 >;
 
@@ -58,11 +59,18 @@ export abstract class DescendantNode<
 		Definition extends DescendantNodeDefinition,
 		// eslint-disable-next-line @typescript-eslint/no-explicit-any
 		Spec extends DescendantNodeStateSpec<any>,
+		Parent extends AnyParentNode,
 		Child extends AnyChildNode | null = null,
 	>
-	extends InstanceNode<Definition, Spec, Child>
-	implements BaseNode, EvaluationContext, SubscribableDependency
+	extends InstanceNode<Definition, Spec, Parent, Child>
+	implements BaseNode, XFormsXPathPrimaryInstanceDescendantNode, EvaluationContext
 {
+	/**
+	 * Partial implementation of {@link isAttached}, used to check whether `this`
+	 * is present in {@link parent}'s children state.
+	 */
+	protected readonly isAttachedDescendant: Accessor<boolean>;
+
 	readonly hasReadonlyAncestor: Accessor<boolean> = () => {
 		const { parent } = this;
 
@@ -97,51 +105,88 @@ export abstract class DescendantNode<
 
 	readonly isRequired: Accessor<boolean>;
 
+	// XFormsXPathPrimaryInstanceDescendantNode
+
+	/**
+	 * WARNING! Ideally, this would be an abstract property, defined by each
+	 * concrete subclass (or other intermediate abstract classes, where
+	 * appropriate). Unfortunately it must be assigned here, so it will be present
+	 * for certain XPath DOM adapter functionality **during** each concrete node's
+	 * construction.
+	 *
+	 * Those subclasses nevertheless override this same property, assigning the
+	 * same value, for the purposes of narrowing the XPath node kind semantics
+	 * appropriate for each node type.
+	 */
+	override readonly [XPathNodeKindKey]: XFormsXPathPrimaryInstanceDescendantNodeKind;
 	readonly root: Root;
-	readonly evaluator: XFormsXPathEvaluator;
-	readonly contextNode: Element;
+
+	// BaseNode
+	abstract override readonly nodeType: InstanceNodeType;
+
+	// EvaluationContext
+	readonly isAttached: Accessor<boolean>;
+	readonly evaluator: EngineXPathEvaluator;
+	override readonly contextNode: PrimaryInstanceXPathChildNode =
+		this as AnyDescendantNode as PrimaryInstanceXPathChildNode;
+	readonly getActiveLanguage: Accessor<ActiveLanguage>;
 
 	constructor(
-		override readonly parent: DescendantNodeParent<Definition>,
+		override readonly parent: Parent,
 		override readonly definition: Definition,
 		options?: DescendantNodeOptions
 	) {
 		super(parent.engineConfig, parent, definition, options);
 
-		const { evaluator, root } = parent;
+		if (this.isRoot()) {
+			this.root = this;
+		} else {
+			this.root = parent.root;
+		}
 
-		this.root = root;
-		this.evaluator = evaluator;
-		this.contextNode = this.initializeContextNode(parent.contextNode, definition.nodeName);
+		const { evaluator } = parent;
 
-		const { readonly, relevant, required } = definition.bind;
+		// See notes on property declaration
+		if (definition.type === 'repeat-range') {
+			this[XPathNodeKindKey] = XFORMS_XPATH_NODE_RANGE_KIND;
+		} else {
+			this[XPathNodeKindKey] = 'element';
+		}
 
-		this.isSelfReadonly = createComputedExpression(this, readonly);
-		this.isSelfRelevant = createComputedExpression(this, relevant);
-		this.isRequired = createComputedExpression(this, required);
-	}
+		const self = this as AnyDescendantNode as AnyChildNode;
 
-	protected createContextNode(parentContextNode: Element, nodeName: string): Element {
-		return parentContextNode.ownerDocument.createElement(nodeName);
-	}
+		this.isAttachedDescendant = this.scope.runTask(() => {
+			return createMemo(() => {
+				for (const child of parent.getChildren()) {
+					if (child === self) {
+						return true;
+					}
+				}
 
-	/**
-	 * Currently expected to be overridden by...
-	 *
-	 * - Repeat range: returns its parent's context node, because it doesn't have
-	 *   a node in the primary instance tree.
-	 *
-	 * - Repeat instance: returns its created context node, but overrides handles
-	 *   appending behavior separately (for inserting at the end of its parent
-	 *   range, or even at an arbitrary index within the range, after instance
-	 *   creation is has completed).
-	 */
-	protected initializeContextNode(parentContextNode: Element, nodeName: string): Element {
-		const element = this.createContextNode(parentContextNode, nodeName);
+				return false;
+			});
+		});
+
+		this.isAttached = this.scope.runTask(() => {
+			return createMemo(() => {
+				return this.parent.isAttached() && this.isAttachedDescendant();
+			});
+		});
+
+		this.evaluator = evaluator;
+		this.getActiveLanguage = parent.getActiveLanguage;
 
-		parentContextNode.append(element);
+		const { readonly, relevant, required } = definition.bind;
 
-		return element;
+		this.isSelfReadonly = createComputedExpression(this, readonly, {
+			defaultValue: true,
+		});
+		this.isSelfRelevant = createComputedExpression(this, relevant, {
+			defaultValue: false,
+		});
+		this.isRequired = createComputedExpression(this, required, {
+			defaultValue: false,
+		});
 	}
 
 	/**

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,18 @@ 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;
+}
 
 export interface InstanceNodeStateSpec<Value = never> {
 	readonly reference: Accessor<string> | string;
@@ -28,7 +41,7 @@ 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 children: Accessor<readonly FormNodeID[]> | null;
 	readonly valueOptions: Accessor<null> | Accessor<readonly unknown[]> | null;
 	readonly value: Signal<Value> | SimpleAtomicState<Value> | null;
 }
@@ -71,19 +84,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,10 +129,10 @@ 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>;
 
@@ -120,15 +140,15 @@ export abstract class InstanceNode<
 
 	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 = (
@@ -149,114 +169,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;
-	}
-
-	/**
-	 * @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[];
+		const self = this as AnyInstanceNode as AnyNode;
 
-	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.
 	 */
-	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;
+	abstract getChildren(this: AnyInstanceNode): readonly AnyChildNode[];
+
+	// XFormsXPathNode
+	/**
+	 * @todo Values as text nodes(?)
+	 */
+	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>;
 
@@ -85,7 +98,11 @@ export abstract class UnsupportedControl<Type extends UnsupportedControlNodeType
 		return this.validation.currentState;
 	}
 
+	readonly submissionState: SubmissionState;
+
 	// ValueContext
+	abstract override readonly contextNode: AnyUnsupportedControl & this;
+
 	readonly encodeValue = (instanceValue: unknown): string => {
 		const encoded = instanceValue;
 
@@ -128,6 +145,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