@getodk/xforms-engine 0.1.1 → 0.3.0

package/src/instance/abstract/InstanceNode.ts

@@ -1,8 +1,9 @@
 import type { XFormsXPathEvaluator } from '@getodk/xpath';
 import type { Accessor, Signal } from 'solid-js';
-import { createSignal } 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 { NodeValidationState } from '../../client/validation.ts';
 import type { TextRange } from '../../index.ts';
 import type { MaterializedChildren } from '../../lib/reactivity/materializeCurrentStateChildren.ts';
 import type { CurrentState } from '../../lib/reactivity/node-state/createCurrentState.ts';
@@ -40,10 +41,6 @@ type AnyInstanceNode = InstanceNode<
 	any
 >;
 
-interface InitializedStateOptions<T, K extends keyof T> {
-	readonly uninitializedFallback: T[K];
-}
-
 /**
  * This type has the same effect as {@link MaterializedChildren}, but abstractly
  * handles leaf node types as well.
@@ -61,6 +58,21 @@ export type InstanceNodeCurrentState<
 				: null;
 		};
 
+interface ComputableReferenceNode {
+	readonly parent: AnyParentNode | null;
+	readonly definition: AnyNodeDefinition;
+}
+
+type ComputeInstanceNodeReference = <This extends ComputableReferenceNode>(
+	this: This,
+	parent: This['parent'],
+	definition: This['definition']
+) => string;
+
+export interface InstanceNodeOptions {
+	readonly computeReference?: () => string;
+}
+
 export abstract class InstanceNode<
 		Definition extends AnyNodeDefinition,
 		// eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -69,60 +81,32 @@ export abstract class InstanceNode<
 	>
 	implements BaseNode, EvaluationContext, SubscribableDependency
 {
-	protected readonly isStateInitialized: Accessor<boolean>;
-
 	protected abstract readonly state: SharedNodeState<Spec>;
 	protected abstract readonly engineState: EngineState<Spec>;
 
 	/**
-	 * Provides a generalized mechanism for accessing a reactive state value
-	 * during a node's construction, while {@link engineState} is still being
-	 * defined and thus isn't assigned.
-	 *
-	 * The fallback value specified in {@link options} will be returned on access
-	 * until {@link isStateInitialized} returns true. This ensures:
-	 *
-	 * - a value of the expected type will be available
-	 * - any read access will become reactive to the actual state, once it has
-	 *   been initialized and {@link engineState} is assigned
-	 *
-	 * @todo This is one among several chicken/egg problems encountered trying to
-	 * support state initialization in which some aspects of the state derive from
-	 * other aspects of it. It would be nice to dispense with this entirely. But
-	 * if it must persist, we should also consider replacing the method with a
-	 * direct accessor once state initialization completes, so the initialized
-	 * check is only called until it becomes impertinent.
+	 * @package Exposed on every node type to facilitate inheritance, as well as
+	 * conditional behavior for value nodes.
 	 */
-	protected getInitializedState<K extends keyof EngineState<Spec>>(
-		key: K,
-		options: InitializedStateOptions<EngineState<Spec>, K>
-	): EngineState<Spec>[K] {
-		if (this.isStateInitialized()) {
-			return this.engineState[key];
-		}
+	abstract readonly hasReadonlyAncestor: Accessor<boolean>;
 
-		return options.uninitializedFallback;
-	}
+	/**
+	 * @package Exposed on every node type to facilitate inheritance, as well as
+	 * conditional behavior for value nodes.
+	 */
+	abstract readonly isReadonly: Accessor<boolean>;
 
 	/**
 	 * @package Exposed on every node type to facilitate inheritance, as well as
 	 * conditional behavior for value nodes.
 	 */
-	get isReadonly(): boolean {
-		return (this as AnyInstanceNode).getInitializedState('readonly', {
-			uninitializedFallback: false,
-		});
-	}
+	abstract readonly hasNonRelevantAncestor: Accessor<boolean>;
 
 	/**
 	 * @package Exposed on every node type to facilitate inheritance, as well as
 	 * conditional behavior for value nodes.
 	 */
-	get isRelevant(): boolean {
-		return (this as AnyInstanceNode).getInitializedState('relevant', {
-			uninitializedFallback: true,
-		});
-	}
+	abstract readonly isRelevant: Accessor<boolean>;
 
 	// BaseNode: identity
 	readonly nodeId: NodeID;
@@ -130,8 +114,12 @@ export abstract class InstanceNode<
 	// BaseNode: node types and variants (e.g. for narrowing)
 	abstract readonly nodeType: InstanceNodeType;
 
+	abstract readonly appearances: NodeAppearances<Definition>;
+
 	abstract readonly currentState: InstanceNodeCurrentState<Spec, Child>;
 
+	abstract readonly validationState: NodeValidationState;
+
 	// BaseNode: structural
 	abstract readonly root: Root;
 
@@ -141,35 +129,40 @@ export abstract class InstanceNode<
 	// EvaluationContext *and* Subscribable: node-specific
 	readonly scope: ReactiveScope;
 
+	readonly computeReference: ComputeInstanceNodeReference;
+
+	protected readonly computeChildStepReference: ComputeInstanceNodeReference = (
+		parent,
+		definition
+	): string => {
+		if (parent == null) {
+			throw new Error(
+				'Cannot compute child step reference of node without parent (was this called from `Root`?)'
+			);
+		}
+
+		return `${parent.contextReference()}/${definition.nodeName}`;
+	};
+
 	// EvaluationContext: node-specific
-	get contextReference(): string {
+	readonly contextReference = (): string => {
 		return this.computeReference(this.parent, this.definition);
-	}
+	};
 
 	abstract readonly contextNode: Element;
 
 	constructor(
 		readonly engineConfig: InstanceConfig,
 		readonly parent: AnyParentNode | null,
-		readonly definition: Definition
+		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 checkStateInitialized = () => this.engineState != null;
-		const [isStateInitialized, setStateInitialized] = createSignal(checkStateInitialized());
-
-		this.isStateInitialized = isStateInitialized;
-
-		queueMicrotask(() => {
-			if (checkStateInitialized()) {
-				setStateInitialized(true);
-			} else {
-				throw new Error('Node state was never initialized');
-			}
-		});
 	}
 
 	/**
@@ -184,18 +177,13 @@ export abstract class InstanceNode<
 	 */
 	abstract getChildren(this: AnyInstanceNode): readonly AnyChildNode[];
 
-	protected abstract computeReference(
-		parent: AnyInstanceNode | null,
-		definition: Definition
-	): string;
-
-	getNodeByReference(
+	getNodesByReference(
 		this: AnyNode,
 		visited: WeakSet<AnyNode>,
 		dependencyReference: string
-	): SubscribableDependency | null {
+	): readonly SubscribableDependency[] {
 		if (visited.has(this)) {
-			return null;
+			return [];
 		}
 
 		visited.add(this);
@@ -203,39 +191,37 @@ export abstract class InstanceNode<
 		const { nodeset } = this.definition;
 
 		if (dependencyReference === nodeset) {
-			return this;
+			if (this.nodeType === 'repeat-instance') {
+				return [this.parent];
+			}
+
+			return [this];
 		}
 
 		if (
 			dependencyReference.startsWith(`${nodeset}/`) ||
 			dependencyReference.startsWith(`${nodeset}[`)
 		) {
-			const children = this.getChildren();
-
-			if (children == null) {
-				return null;
-			}
-
-			for (const child of children) {
-				const dependency = child.getNodeByReference(visited, dependencyReference);
-
-				if (dependency != null) {
-					return dependency;
-				}
-			}
+			return this.getChildren().flatMap((child) => {
+				return child.getNodesByReference(visited, dependencyReference);
+			});
 		}
 
-		return this.parent?.getNodeByReference(visited, dependencyReference) ?? null;
+		return this.parent?.getNodesByReference(visited, dependencyReference) ?? [];
 	}
 
 	// EvaluationContext: node-relative
-	getSubscribableDependencyByReference(
+	getSubscribableDependenciesByReference(
 		this: AnyNode,
 		reference: string
-	): SubscribableDependency | null {
-		const visited = new WeakSet<SubscribableDependency>();
+	): readonly SubscribableDependency[] {
+		if (this.nodeType === 'root') {
+			const visited = new WeakSet<AnyNode>();
 
-		return this.getNodeByReference(visited, reference);
+			return this.getNodesByReference(visited, reference);
+		}
+
+		return this.root.getSubscribableDependenciesByReference(reference);
 	}
 
 	// SubscribableDependency
@@ -247,11 +233,22 @@ export abstract class InstanceNode<
 	subscribe(): void {
 		const { engineState } = this;
 
-		if (engineState.relevant) {
-			engineState.reference;
-			engineState.relevant;
-			engineState.children;
-			engineState.value;
-		}
+		// 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.
+		engineState.reference;
+		engineState.relevant;
+		engineState.children;
+		engineState.value;
 	}
 }

package/src/instance/children.ts

@@ -1,14 +1,20 @@
 import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
-import { SelectDefinition } from '../body/control/select/SelectDefinition.ts';
 import type { GroupDefinition } from '../client/GroupNode.ts';
 import type { SubtreeDefinition } from '../client/SubtreeNode.ts';
+import type { LeafNodeDefinition } from '../model/LeafNodeDefinition.ts';
 import type { SubtreeDefinition as ModelSubtreeDefinition } from '../model/SubtreeDefinition.ts';
+import { NoteNodeDefinition } from '../parse/NoteNodeDefinition.ts';
 import { Group } from './Group.ts';
-import { RepeatRange } from './RepeatRange.ts';
-import { SelectField, type SelectFieldDefinition } from './SelectField.ts';
+import type { GeneralChildNode, GeneralParentNode } from './hierarchy.ts';
+import { ModelValue, type ModelValueDefinition } from './ModelValue.ts';
+import { Note } from './Note.ts';
+import { RepeatRangeControlled } from './repeat/RepeatRangeControlled.ts';
+import { RepeatRangeUncontrolled } from './repeat/RepeatRangeUncontrolled.ts';
+import type { SelectFieldDefinition } from './SelectField.ts';
+import { SelectField } from './SelectField.ts';
+import type { StringFieldDefinition } from './StringField.ts';
 import { StringField } from './StringField.ts';
 import { Subtree } from './Subtree.ts';
-import type { GeneralChildNode, GeneralParentNode } from './hierarchy.ts';
 
 const isSubtreeDefinition = (
 	definition: ModelSubtreeDefinition
@@ -16,6 +22,22 @@ const isSubtreeDefinition = (
 	return definition.bodyElement == null;
 };
 
+type ControlNodeDefinition = SelectFieldDefinition | StringFieldDefinition;
+
+type AnyLeafNodeDefinition = ControlNodeDefinition | ModelValueDefinition;
+
+const isModelValueDefinition = (
+	definition: LeafNodeDefinition
+): definition is ModelValueDefinition => {
+	return definition.bodyElement == null;
+};
+
+const isStringFieldDefinition = (
+	definition: ControlNodeDefinition
+): definition is StringFieldDefinition => {
+	return definition.bodyElement.type === 'input';
+};
+
 export const buildChildren = (parent: GeneralParentNode): GeneralChildNode[] => {
 	const { children } = parent.definition;
 
@@ -32,16 +54,31 @@ export const buildChildren = (parent: GeneralParentNode): GeneralChildNode[] =>
 				return new Group(parent, child as GroupDefinition);
 			}
 
-			case 'repeat-sequence': {
-				return new RepeatRange(parent, child);
+			case 'repeat-range': {
+				if (child.isControlled()) {
+					return new RepeatRangeControlled(parent, child);
+				}
+
+				return new RepeatRangeUncontrolled(parent, child);
 			}
 
-			case 'value-node': {
-				if (child.bodyElement instanceof SelectDefinition) {
-					return new SelectField(parent, child as SelectFieldDefinition);
+			case 'leaf-node': {
+				if (child instanceof NoteNodeDefinition) {
+					return new Note(parent, child);
+				}
+
+				// More specific type helps with narrowing below
+				const leafChild: AnyLeafNodeDefinition = child;
+
+				if (isModelValueDefinition(leafChild)) {
+					return new ModelValue(parent, leafChild);
+				}
+
+				if (isStringFieldDefinition(leafChild)) {
+					return new StringField(parent, leafChild);
 				}
 
-				return new StringField(parent, child);
+				return new SelectField(parent, leafChild);
 			}
 
 			default: {

package/src/instance/hierarchy.ts

@@ -1,11 +1,16 @@
 import type { Group } from './Group.ts';
-import type { RepeatInstance } from './RepeatInstance.ts';
-import type { RepeatRange } from './RepeatRange.ts';
+import type { ModelValue } from './ModelValue.ts';
+import type { Note } from './Note.ts';
+import type { RepeatInstance } from './repeat/RepeatInstance.ts';
+import type { RepeatRangeControlled } from './repeat/RepeatRangeControlled.ts';
+import type { RepeatRangeUncontrolled } from './repeat/RepeatRangeUncontrolled.ts';
 import type { Root } from './Root.ts';
 import type { SelectField } from './SelectField.ts';
 import type { StringField } from './StringField.ts';
 import type { Subtree } from './Subtree.ts';
 
+export type RepeatRange = RepeatRangeControlled | RepeatRangeUncontrolled;
+
 // prettier-ignore
 export type AnyNode =
 	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
@@ -14,6 +19,8 @@ export type AnyNode =
 	| Subtree
 	| RepeatRange
 	| RepeatInstance
+	| Note
+	| ModelValue
 	| StringField
 	| SelectField;
 
@@ -41,6 +48,8 @@ export type AnyChildNode =
 	| Subtree
 	| RepeatRange
 	| RepeatInstance
+	| ModelValue
+	| Note
 	| StringField
 	| SelectField;
 
@@ -50,5 +59,15 @@ export type GeneralChildNode =
 	| Group
 	| Subtree
 	| RepeatRange
+	| ModelValue
+	| Note
+	| StringField
+	| SelectField;
+
+// prettier-ignore
+export type AnyValueNode =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| ModelValue
+	| Note
 	| StringField
 	| SelectField;

package/src/instance/index.ts

@@ -31,7 +31,7 @@ export const initializeForm = async (
 	const sourceXML = await retrieveSourceXMLResource(input, engineConfig);
 	const form = new XFormDefinition(sourceXML);
 
-	return Root.initialize(form.xformDOM, form.model.root, engineConfig);
+	return new Root(form.xformDOM, form.model.root, engineConfig);
 };
 
 initializeForm satisfies InitializeForm;

package/src/instance/internal-api/EvaluationContext.ts

@@ -1,4 +1,5 @@
 import type { XFormsXPathEvaluator } from '@getodk/xpath';
+import type { Accessor } from 'solid-js';
 import type { DependentExpression } from '../../expression/DependentExpression.ts';
 import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
 import type { SubscribableDependency } from './SubscribableDependency.ts';
@@ -27,15 +28,13 @@ export interface EvaluationContext {
 	 * Produces the current absolute reference to the {@link contextNode}, where
 	 * the absolute `/` resolves to the active form state's primary instance root.
 	 */
-	get contextReference(): string;
+	readonly contextReference: Accessor<string>;
 
 	readonly contextNode: Node;
 
 	/**
-	 * Resolves a nodeset reference, possibly relative to the
-	 * {@link EvaluationContext.contextNode}.
+	 * Resolves nodes corresponding to the provided node-set reference, possibly
+	 * relative to the {@link EvaluationContext.contextNode}.
 	 */
-	readonly getSubscribableDependencyByReference: (
-		reference: string
-	) => SubscribableDependency | null;
+	getSubscribableDependenciesByReference(reference: string): readonly SubscribableDependency[];
 }

package/src/instance/internal-api/ValidationContext.ts

@@ -0,0 +1,23 @@
+import type { BindComputation } from '../../model/BindComputation.ts';
+import type { MessageDefinition } from '../../parse/text/MessageDefinition.ts';
+import type { EvaluationContext } from './EvaluationContext.ts';
+import type { SubscribableDependency } from './SubscribableDependency.ts';
+
+interface ValidationContextDefinitionBind {
+	readonly constraint: BindComputation<'constraint'>;
+	readonly constraintMsg: MessageDefinition<'constraintMsg'> | null;
+	readonly required: BindComputation<'required'>;
+	readonly requiredMsg: MessageDefinition<'requiredMsg'> | null;
+}
+
+interface ValidationContextDefinition {
+	readonly bind: ValidationContextDefinitionBind;
+}
+
+export interface ValidationContext extends EvaluationContext, SubscribableDependency {
+	readonly definition: ValidationContextDefinition;
+
+	isRelevant(): boolean;
+	isRequired(): boolean;
+	isBlank(): boolean;
+}

package/src/instance/internal-api/ValueContext.ts

@@ -19,8 +19,8 @@ export interface ValueContext<RuntimeValue> extends EvaluationContext {
 	readonly definition: ValueContextDefinition;
 	readonly contextNode: Element;
 
-	get isReadonly(): boolean;
-	get isRelevant(): boolean;
+	isReadonly(): boolean;
+	isRelevant(): boolean;
 
 	readonly encodeValue: (this: unknown, runtimeValue: RuntimeValue) => InstanceValue;
 	readonly decodeValue: (this: unknown, instanceValue: InstanceValue) => RuntimeValue;