@getodk/xforms-engine 0.2.0 → 0.3.0

package/src/expression/DependentExpression.ts

@@ -1,10 +1,20 @@
 import type { XFormsXPathEvaluator } from '@getodk/xpath';
-import { getNodesetDependencies, isItextFunctionCalled } from '../lib/xpath/analysis.ts';
+import { resolveDependencyNodesets } from '../parse/xpath/dependency-analysis.ts';
+import type {
+	ConstantExpression,
+	ConstantTruthyExpression,
+} from '../parse/xpath/semantic-analysis.ts';
+import {
+	isConstantExpression,
+	isConstantTruthyExpression,
+	isTranslationExpression,
+} from '../parse/xpath/semantic-analysis.ts';
 import type { DependencyContext } from './DependencyContext.ts';
 
 const evaluatorMethodsByResultType = {
 	boolean: 'evaluateBoolean',
 	nodes: 'evaluateNodes',
+	number: 'evaluateNumber',
 	string: 'evaluateString',
 } as const;
 
@@ -20,11 +30,6 @@ export type DependentExpressionResult<Type extends DependentExpressionResultType
 >;
 
 interface SemanticDependencyOptions {
-	/**
-	 * @default false
-	 */
-	readonly parentContext?: boolean | undefined;
-
 	/**
 	 * @default false
 	 */
@@ -37,18 +42,24 @@ interface DependentExpressionOptions {
 	 */
 	readonly ignoreContextReference?: boolean;
 
-	/**
-	 * @default true
-	 */
-	readonly ignoreNullExpressions?: boolean;
-
 	readonly semanticDependencies?: SemanticDependencyOptions;
 }
 
+export interface ConstantDependentExpression<Type extends DependentExpressionResultType>
+	extends DependentExpression<Type> {
+	readonly expression: ConstantExpression;
+}
+
+export interface ConstantTruthyDependentExpression extends ConstantDependentExpression<'boolean'> {
+	readonly expression: ConstantTruthyExpression;
+}
+
 export class DependentExpression<Type extends DependentExpressionResultType> {
 	readonly dependencyReferences: ReadonlySet<string> = new Set();
 	readonly isTranslated: boolean = false;
 	readonly evaluatorMethod: DependentExpressionEvaluatorMethod<Type>;
+	readonly constantExpression: ConstantExpression | null;
+	readonly constantTruthyExpression: ConstantTruthyExpression | null;
 
 	constructor(
 		context: DependencyContext,
@@ -56,34 +67,33 @@ export class DependentExpression<Type extends DependentExpressionResultType> {
 		readonly expression: string,
 		options: DependentExpressionOptions = {}
 	) {
+		if (resultType === 'boolean' && isConstantTruthyExpression(expression)) {
+			this.constantTruthyExpression = expression;
+			this.constantExpression = expression;
+		} else if (isConstantExpression(expression)) {
+			this.constantTruthyExpression = null;
+			this.constantExpression = expression;
+		} else {
+			this.constantTruthyExpression = null;
+			this.constantExpression = null;
+		}
+
 		this.evaluatorMethod = evaluatorMethodsByResultType[resultType];
 
 		const {
 			ignoreContextReference = false,
-			ignoreNullExpressions = true,
 			semanticDependencies = {
-				parentContext: false,
 				translations: false,
 			},
 		} = options;
 
-		const dependencyReferences = new Set<string>(
-			getNodesetDependencies(expression, {
-				contextReference: context.reference,
-				ignoreContextReference,
-				ignoreNullExpressions,
+		this.dependencyReferences = new Set(
+			resolveDependencyNodesets(context.reference, expression, {
+				ignoreReferenceToContextPath: ignoreContextReference,
 			})
 		);
 
-		const parentDependency = semanticDependencies.parentContext ? context.parentReference : null;
-
-		if (parentDependency != null) {
-			dependencyReferences.add(parentDependency);
-		}
-
-		this.dependencyReferences = dependencyReferences;
-
-		const isTranslated = semanticDependencies.translations && isItextFunctionCalled(expression);
+		const isTranslated = semanticDependencies.translations && isTranslationExpression(expression);
 
 		if (isTranslated) {
 			this.isTranslated = true;
@@ -93,6 +103,14 @@ export class DependentExpression<Type extends DependentExpressionResultType> {
 		context.registerDependentExpression(this);
 	}
 
+	isConstantExpression(): this is ConstantDependentExpression<Type> {
+		return this.constantExpression != null;
+	}
+
+	isConstantTruthyExpression(): this is ConstantTruthyDependentExpression {
+		return this.resultType === 'boolean' && this.constantTruthyExpression != null;
+	}
+
 	toString(): string | null {
 		return this.expression;
 	}

package/src/index.ts

@@ -3,26 +3,33 @@ import { initializeForm as engine__initializeForm } from './instance/index.ts';
 
 export const initializeForm: InitializeForm = engine__initializeForm;
 
+export * as constants from './client/constants.ts';
 export type * from './client/EngineConfig.ts';
 export type * from './client/FormLanguage.ts';
 export type * from './client/GroupNode.ts';
-export type * from './client/OpaqueReactiveObjectFactory.ts';
-export type * from './client/RepeatInstanceNode.ts';
-export type * from './client/RepeatRangeNode.ts';
-export type * from './client/RootNode.ts';
-export type * from './client/SelectNode.ts';
-export type * from './client/StringNode.ts';
-export type * from './client/SubtreeNode.ts';
-export type * from './client/TextRange.ts';
 export type {
 	AnyChildNode,
+	AnyControlNode,
 	AnyLeafNode,
 	AnyNode,
 	AnyParentNode,
 	GeneralChildNode,
 	GeneralParentNode,
+	RepeatRangeNode,
 } from './client/hierarchy.ts';
 export type * from './client/index.ts';
+export type * from './client/ModelValueNode.ts';
+export type * from './client/NoteNode.ts';
+export type * from './client/OpaqueReactiveObjectFactory.ts';
+export type * from './client/repeat/RepeatInstanceNode.ts';
+export type * from './client/repeat/RepeatRangeControlledNode.ts';
+export type * from './client/repeat/RepeatRangeUncontrolledNode.ts';
+export type * from './client/RootNode.ts';
+export type * from './client/SelectNode.ts';
+export type * from './client/StringNode.ts';
+export type * from './client/SubtreeNode.ts';
+export type * from './client/TextRange.ts';
+export type * from './client/validation.ts';
 
 // TODO: notwithstanding potential conflicts with parallel work on `web-forms`
 // (former `ui-vue`), these are the last remaining references **outside of

package/src/instance/Group.ts

@@ -1,6 +1,7 @@
 import type { Accessor } from 'solid-js';
 import type { GroupDefinition, GroupNode, GroupNodeAppearances } from '../client/GroupNode.ts';
-import type { TextRange } from '../index.ts';
+import type { TextRange } from '../client/TextRange.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';
@@ -10,6 +11,7 @@ import type { EngineState } from '../lib/reactivity/node-state/createEngineState
 import type { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
 import { createSharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
 import { createNodeLabel } from '../lib/reactivity/text/createNodeLabel.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';
@@ -41,6 +43,7 @@ export class Group
 	readonly nodeType = 'group';
 	readonly appearances: GroupNodeAppearances;
 	readonly currentState: MaterializedChildren<CurrentState<GroupStateSpec>, GeneralChildNode>;
+	readonly validationState: AncestorNodeValidationState;
 
 	constructor(parent: GeneralParentNode, definition: GroupDefinition) {
 		super(parent, definition);
@@ -51,6 +54,10 @@ export class Group
 
 		this.childrenState = childrenState;
 
+		const sharedStateOptions = {
+			clientStateFactory: this.engineConfig.stateFactory,
+		};
+
 		const state = createSharedNodeState(
 			this.scope,
 			{
@@ -65,9 +72,7 @@ export class Group
 				valueOptions: null,
 				value: null,
 			},
-			{
-				clientStateFactory: this.engineConfig.stateFactory,
-			}
+			sharedStateOptions
 		);
 
 		this.state = state;
@@ -79,6 +84,7 @@ export class Group
 		);
 
 		childrenState.setChildren(buildChildren(this));
+		this.validationState = createAggregatedViolations(this, sharedStateOptions);
 	}
 
 	getChildren(): readonly GeneralChildNode[] {

package/src/instance/ModelValue.ts

@@ -0,0 +1,104 @@
+import { identity } from '@getodk/common/lib/identity.ts';
+import type { ModelValueNode } from '../client/ModelValueNode.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';
+import type { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
+import { createSharedNodeState } 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 type { LeafNodeDefinition } from '../model/LeafNodeDefinition.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 ModelValueDefinition extends LeafNodeDefinition {
+	readonly bodyElement: null;
+}
+
+interface ModelValueStateSpec extends DescendantNodeStateSpec<string> {
+	readonly label: null;
+	readonly hint: null;
+	readonly children: null;
+	readonly value: SimpleAtomicState<string>;
+	readonly valueOptions: null;
+}
+
+export class ModelValue
+	extends DescendantNode<ModelValueDefinition, ModelValueStateSpec, null>
+	implements
+		ModelValueNode,
+		EvaluationContext,
+		SubscribableDependency,
+		ValidationContext,
+		ValueContext<string>
+{
+	private readonly validation: SharedValidationState;
+	protected readonly state: SharedNodeState<ModelValueStateSpec>;
+
+	// InstanceNode
+	protected engineState: EngineState<ModelValueStateSpec>;
+
+	// ModelValueNode
+	readonly nodeType = 'model-value';
+	readonly appearances = null;
+	readonly currentState: CurrentState<ModelValueStateSpec>;
+
+	get validationState(): LeafNodeValidationState {
+		return this.validation.currentState;
+	}
+
+	// ValueContext
+	readonly encodeValue = identity<string>;
+	readonly decodeValue = identity<string>;
+
+	constructor(parent: GeneralParentNode, definition: ModelValueDefinition) {
+		super(parent, definition);
+
+		const sharedStateOptions = {
+			clientStateFactory: this.engineConfig.stateFactory,
+		};
+
+		const state = createSharedNodeState(
+			this.scope,
+			{
+				reference: this.contextReference,
+				readonly: this.isReadonly,
+				relevant: this.isRelevant,
+				required: this.isRequired,
+
+				label: null,
+				hint: null,
+				children: null,
+				valueOptions: null,
+				value: createValueState(this),
+			},
+			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
+	getChildren(): readonly [] {
+		return [];
+	}
+}

package/src/instance/Note.ts

@@ -0,0 +1,142 @@
+import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
+import { identity } from '@getodk/common/lib/identity.ts';
+import type { Accessor } from 'solid-js';
+import type { NoteNode, NoteNodeAppearances } from '../client/NoteNode.ts';
+import type { TextRange } from '../client/TextRange.ts';
+import type { AnyViolation, LeafNodeValidationState } from '../client/validation.ts';
+import { createNoteReadonlyThunk } from '../lib/reactivity/createNoteReadonlyThunk.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';
+import type { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
+import { createSharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
+import { createFieldHint } from '../lib/reactivity/text/createFieldHint.ts';
+import { createNodeLabel } from '../lib/reactivity/text/createNodeLabel.ts';
+import { createNoteText, type ComputedNoteText } from '../lib/reactivity/text/createNoteText.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 type { NoteNodeDefinition } from '../parse/NoteNodeDefinition.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';
+
+interface NoteStateSpec extends DescendantNodeStateSpec<string> {
+	readonly readonly: Accessor<true>;
+	readonly noteText: ComputedNoteText;
+	readonly label: Accessor<TextRange<'label', 'form'> | null>;
+	readonly hint: Accessor<TextRange<'hint', 'form'> | null>;
+	readonly children: null;
+	readonly value: SimpleAtomicState<string>;
+	readonly valueOptions: null;
+}
+
+export class Note
+	extends DescendantNode<NoteNodeDefinition, NoteStateSpec, null>
+	implements
+		NoteNode,
+		EvaluationContext,
+		SubscribableDependency,
+		ValidationContext,
+		ValueContext<string>
+{
+	private readonly validation: SharedValidationState;
+	protected readonly state: SharedNodeState<NoteStateSpec>;
+
+	// InstanceNode
+	protected engineState: EngineState<NoteStateSpec>;
+
+	// NoteNode
+	readonly nodeType = 'note';
+	readonly appearances: NoteNodeAppearances;
+	readonly currentState: CurrentState<NoteStateSpec>;
+
+	get validationState(): LeafNodeValidationState {
+		return this.validation.currentState;
+	}
+
+	// ValueContext
+	readonly encodeValue = identity<string>;
+
+	readonly decodeValue = identity<string>;
+
+	constructor(parent: GeneralParentNode, definition: NoteNodeDefinition) {
+		super(parent, definition);
+
+		this.appearances = definition.bodyElement.appearances;
+
+		const sharedStateOptions = {
+			clientStateFactory: this.engineConfig.stateFactory,
+		};
+
+		const isReadonly = createNoteReadonlyThunk(this, definition.bind.readonly);
+		const noteTextComputation = createNoteText(this, definition.noteTextDefinition);
+
+		let noteText: ComputedNoteText;
+		let label: Accessor<TextRange<'label', 'form'> | null>;
+		let hint: Accessor<TextRange<'hint', 'form'> | null>;
+
+		switch (noteTextComputation.role) {
+			case 'label': {
+				noteText = noteTextComputation.label;
+				label = noteTextComputation.label;
+				hint = createFieldHint(this, definition);
+
+				break;
+			}
+
+			case 'hint': {
+				noteText = noteTextComputation.hint;
+				label = createNodeLabel(this, definition);
+				hint = noteTextComputation.hint;
+
+				break;
+			}
+
+			default:
+				throw new UnreachableError(noteTextComputation);
+		}
+
+		const state = createSharedNodeState(
+			this.scope,
+			{
+				reference: this.contextReference,
+				readonly: isReadonly,
+				relevant: this.isRelevant,
+				required: this.isRequired,
+
+				label,
+				hint,
+				noteText,
+
+				children: null,
+				valueOptions: null,
+				value: createValueState(this),
+			},
+			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
+	getChildren(): readonly [] {
+		return [];
+	}
+}

package/src/instance/Root.ts

@@ -5,6 +5,7 @@ import type { XFormDOM } from '../XFormDOM.ts';
 import type { BodyClassList } from '../body/BodyDefinition.ts';
 import type { ActiveLanguage, FormLanguage, FormLanguages } from '../client/FormLanguage.ts';
 import type { RootNode } from '../client/RootNode.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';
@@ -13,6 +14,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 { RootDefinition } from '../model/RootDefinition.ts';
 import { InstanceNode } from './abstract/InstanceNode.ts';
 import { buildChildren } from './children.ts';
@@ -114,6 +116,7 @@ export class Root
 	readonly appearances = null;
 	readonly classes: BodyClassList;
 	readonly currentState: MaterializedChildren<CurrentState<RootStateSpec>, GeneralChildNode>;
+	readonly validationState: AncestorNodeValidationState;
 
 	protected readonly instanceDOM: XFormDOM;
 
@@ -152,6 +155,10 @@ export class Root
 		const evaluator = instanceDOM.primaryInstanceEvaluator;
 		const { translations } = evaluator;
 		const { defaultLanguage, languages } = getInitialLanguageState(translations);
+		const sharedStateOptions = {
+			clientStateFactory: this.engineConfig.stateFactory,
+		};
+
 		const state = createSharedNodeState(
 			this.scope,
 			{
@@ -166,9 +173,7 @@ export class Root
 				value: null,
 				children: childrenState.childIds,
 			},
-			{
-				clientStateFactory: engineConfig.stateFactory,
-			}
+			sharedStateOptions
 		);
 
 		this.state = state;
@@ -189,6 +194,7 @@ export class Root
 		this.languages = languages;
 
 		childrenState.setChildren(buildChildren(this));
+		this.validationState = createAggregatedViolations(this, sharedStateOptions);
 	}
 
 	getChildren(): readonly GeneralChildNode[] {

package/src/instance/SelectField.ts

@@ -3,7 +3,8 @@ import type { Accessor } from 'solid-js';
 import { untrack } from 'solid-js';
 import type { AnySelectDefinition } from '../body/control/select/SelectDefinition.ts';
 import type { SelectItem, SelectNode, SelectNodeAppearances } from '../client/SelectNode.ts';
-import type { TextRange } from '../index.ts';
+import type { TextRange } from '../client/TextRange.ts';
+import type { AnyViolation, LeafNodeValidationState } from '../client/validation.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';
@@ -13,16 +14,19 @@ 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 SelectFieldDefinition extends ValueNodeDefinition {
+export interface SelectFieldDefinition extends LeafNodeDefinition {
 	readonly bodyElement: AnySelectDefinition;
 }
 
@@ -40,9 +44,11 @@ export class SelectField
 		SelectNode,
 		EvaluationContext,
 		SubscribableDependency,
+		ValidationContext,
 		ValueContext<readonly SelectItem[]>
 {
 	private readonly selectExclusive: boolean;
+	private readonly validation: SharedValidationState;
 
 	// InstanceNode
 	protected readonly state: SharedNodeState<SelectFieldStateSpec>;
@@ -53,6 +59,10 @@ export class SelectField
 	readonly appearances: SelectNodeAppearances;
 	readonly currentState: CurrentState<SelectFieldStateSpec>;
 
+	get validationState(): LeafNodeValidationState {
+		return this.validation.currentState;
+	}
+
 	// ValueContext
 	readonly encodeValue = (runtimeValue: readonly SelectItem[]): string => {
 		const itemValues = new Set(runtimeValue.map(({ value }) => value));
@@ -90,6 +100,10 @@ export class SelectField
 
 		this.getValueOptions = valueOptions;
 
+		const sharedStateOptions = {
+			clientStateFactory: this.engineConfig.stateFactory,
+		};
+
 		const state = createSharedNodeState(
 			this.scope,
 			{
@@ -104,14 +118,17 @@ export class SelectField
 				value: createValueState(this),
 				valueOptions,
 			},
-			{
-				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;
 	}
 
 	protected getSelectItemsByValue(
@@ -201,4 +218,9 @@ export class SelectField
 	getChildren(): readonly [] {
 		return [];
 	}
+
+	// ValidationContext
+	isBlank(): boolean {
+		return this.engineState.value.length === 0;
+	}
 }