@getodk/xforms-engine 0.2.0 → 0.3.0

package/src/instance/StringField.ts

@@ -2,7 +2,8 @@ import { identity } from '@getodk/common/lib/identity.ts';
 import type { Accessor } from 'solid-js';
 import type { InputDefinition } from '../body/control/InputDefinition.ts';
 import type { StringNode, StringNodeAppearances } from '../client/StringNode.ts';
-import type { TextRange } from '../index.ts';
+import type { TextRange } from '../client/TextRange.ts';
+import type { AnyViolation, LeafNodeValidationState } from '../client/validation.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';
@@ -11,17 +12,20 @@ import { createSharedNodeState } from '../lib/reactivity/node-state/createShared
 import { createFieldHint } from '../lib/reactivity/text/createFieldHint.ts';
 import { createNodeLabel } from '../lib/reactivity/text/createNodeLabel.ts';
 import type { SimpleAtomicState } from '../lib/reactivity/types.ts';
-import type { ValueNodeDefinition } from '../model/ValueNodeDefinition.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 { Root } from './Root.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 { ValidationContext } from './internal-api/ValidationContext.ts';
 import type { ValueContext } from './internal-api/ValueContext.ts';
 
-export interface StringFieldDefinition extends ValueNodeDefinition {
-	readonly bodyElement: InputDefinition | null;
+export interface StringFieldDefinition extends LeafNodeDefinition {
+	readonly bodyElement: InputDefinition;
 }
 
 interface StringFieldStateSpec extends DescendantNodeStateSpec<string> {
@@ -34,8 +38,14 @@ interface StringFieldStateSpec extends DescendantNodeStateSpec<string> {
 
 export class StringField
 	extends DescendantNode<StringFieldDefinition, StringFieldStateSpec, null>
-	implements StringNode, EvaluationContext, SubscribableDependency, ValueContext<string>
+	implements
+		StringNode,
+		EvaluationContext,
+		SubscribableDependency,
+		ValidationContext,
+		ValueContext<string>
 {
+	private readonly validation: SharedValidationState;
 	protected readonly state: SharedNodeState<StringFieldStateSpec>;
 
 	// InstanceNode
@@ -46,6 +56,10 @@ export class StringField
 	readonly appearances: StringNodeAppearances;
 	readonly currentState: CurrentState<StringFieldStateSpec>;
 
+	get validationState(): LeafNodeValidationState {
+		return this.validation.currentState;
+	}
+
 	// ValueContext
 	readonly encodeValue = identity<string>;
 
@@ -54,7 +68,11 @@ export class StringField
 	constructor(parent: GeneralParentNode, definition: StringFieldDefinition) {
 		super(parent, definition);
 
-		this.appearances = (definition.bodyElement?.appearances ?? null) as StringNodeAppearances;
+		this.appearances = definition.bodyElement.appearances;
+
+		const sharedStateOptions = {
+			clientStateFactory: this.engineConfig.stateFactory,
+		};
 
 		const state = createSharedNodeState(
 			this.scope,
@@ -70,14 +88,22 @@ export class StringField
 				valueOptions: null,
 				value: createValueState(this),
 			},
-			{
-				clientStateFactory: this.engineConfig.stateFactory,
-			}
+			sharedStateOptions
 		);
 
 		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

package/src/instance/Subtree.ts

@@ -1,5 +1,6 @@
 import { type Accessor } from 'solid-js';
 import type { SubtreeDefinition, SubtreeNode } from '../client/SubtreeNode.ts';
+import type { AncestorNodeValidationState } from '../client/validation.ts';
 import type { ChildrenState } from '../lib/reactivity/createChildrenState.ts';
 import { createChildrenState } from '../lib/reactivity/createChildrenState.ts';
 import type { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
@@ -8,6 +9,7 @@ import type { CurrentState } from '../lib/reactivity/node-state/createCurrentSta
 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 { createAggregatedViolations } from '../lib/reactivity/validation/createAggregatedViolations.ts';
 import type { DescendantNodeSharedStateSpec } from './abstract/DescendantNode.ts';
 import { DescendantNode } from './abstract/DescendantNode.ts';
 import { buildChildren } from './children.ts';
@@ -38,6 +40,7 @@ export class Subtree
 	readonly nodeType = 'subtree';
 	readonly appearances = null;
 	readonly currentState: MaterializedChildren<CurrentState<SubtreeStateSpec>, GeneralChildNode>;
+	readonly validationState: AncestorNodeValidationState;
 
 	constructor(parent: GeneralParentNode, definition: SubtreeDefinition) {
 		super(parent, definition);
@@ -46,6 +49,10 @@ export class Subtree
 
 		this.childrenState = childrenState;
 
+		const sharedStateOptions = {
+			clientStateFactory: this.engineConfig.stateFactory,
+		};
+
 		const state = createSharedNodeState(
 			this.scope,
 			{
@@ -60,9 +67,7 @@ export class Subtree
 				valueOptions: null,
 				value: null,
 			},
-			{
-				clientStateFactory: this.engineConfig.stateFactory,
-			}
+			sharedStateOptions
 		);
 
 		this.state = state;
@@ -74,6 +79,7 @@ export class Subtree
 		);
 
 		childrenState.setChildren(buildChildren(this));
+		this.validationState = createAggregatedViolations(this, sharedStateOptions);
 	}
 
 	getChildren(): readonly GeneralChildNode[] {

package/src/instance/abstract/DescendantNode.ts

@@ -4,15 +4,14 @@ import type { BaseNode } from '../../client/BaseNode.ts';
 import { createComputedExpression } from '../../lib/reactivity/createComputedExpression.ts';
 import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
 import type { AnyDescendantNodeDefinition } from '../../model/DescendentNodeDefinition.ts';
+import type { LeafNodeDefinition } from '../../model/LeafNodeDefinition.ts';
 import type { AnyNodeDefinition } from '../../model/NodeDefinition.ts';
 import type { RepeatInstanceDefinition } from '../../model/RepeatInstanceDefinition.ts';
-import type { ValueNodeDefinition } from '../../model/ValueNodeDefinition.ts';
-import type { RepeatInstance } from '../RepeatInstance.ts';
-import type { RepeatRange } from '../RepeatRange.ts';
-import type { Root } from '../Root.ts';
-import type { AnyChildNode, GeneralParentNode } from '../hierarchy.ts';
+import type { AnyChildNode, GeneralParentNode, 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';
 import { InstanceNode } from './InstanceNode.ts';
 
@@ -37,7 +36,7 @@ export type DescendantNodeDefinition = Extract<
 
 // prettier-ignore
 export type DescendantNodeParent<Definition extends DescendantNodeDefinition> =
-	Definition extends ValueNodeDefinition
+	Definition extends LeafNodeDefinition
 		? GeneralParentNode
 	: Definition extends RepeatInstanceDefinition
 		? RepeatRange
@@ -96,7 +95,7 @@ export abstract class DescendantNode<
 		return this.isSelfRelevant();
 	};
 
-	protected readonly isRequired: Accessor<boolean>;
+	readonly isRequired: Accessor<boolean>;
 
 	readonly root: Root;
 	readonly evaluator: XFormsXPathEvaluator;

package/src/instance/abstract/InstanceNode.ts

@@ -3,6 +3,7 @@ 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 { 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';
@@ -117,6 +118,8 @@ export abstract class InstanceNode<
 
 	abstract readonly currentState: InstanceNodeCurrentState<Spec, Child>;
 
+	abstract readonly validationState: NodeValidationState;
+
 	// BaseNode: structural
 	abstract readonly root: Root;
 
@@ -230,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,15 +1,20 @@
 import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.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 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
@@ -17,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;
 
@@ -34,24 +55,30 @@ export const buildChildren = (parent: GeneralParentNode): GeneralChildNode[] =>
 			}
 
 			case 'repeat-range': {
-				return new RepeatRange(parent, child);
+				if (child.isControlled()) {
+					return new RepeatRangeControlled(parent, child);
+				}
+
+				return new RepeatRangeUncontrolled(parent, child);
 			}
 
-			case 'value-node': {
-				// TODO: this sort of awkwardness might go away if we embrace a
-				// proliferation of node types throughout.
-				switch (child.bodyElement?.type) {
-					case 'select':
-					case 'select1':
-						return new SelectField(parent, child as SelectFieldDefinition);
+			case 'leaf-node': {
+				if (child instanceof NoteNodeDefinition) {
+					return new Note(parent, child);
+				}
 
-					case 'input':
-					case undefined:
-						return new StringField(parent, child as StringFieldDefinition);
+				// More specific type helps with narrowing below
+				const leafChild: AnyLeafNodeDefinition = child;
 
-					default:
-						throw new UnreachableError(child.bodyElement);
+				if (isModelValueDefinition(leafChild)) {
+					return new ModelValue(parent, leafChild);
 				}
+
+				if (isStringFieldDefinition(leafChild)) {
+					return new StringField(parent, leafChild);
+				}
+
+				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/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;
+}