@getodk/xforms-engine 0.2.0 → 0.4.0

package/src/lib/TokenListParser.ts

@@ -11,16 +11,20 @@ type TokenListIterator<CanonicalToken extends string> = IterableIterator<
 	PartiallyKnownString<CanonicalToken>
 >;
 
+type PassthroughTokenList = Readonly<Record<string, boolean>>;
+
 /**
  * @see {@link TokenListParser}
  */
 // prettier-ignore
-export type TokenList<CanonicalToken extends string = string> = {
-	readonly [Key in TokenListKey<CanonicalToken>]:
-		Key extends SymbolIterator
-			? () => TokenListIterator<CanonicalToken>
-			: boolean;
-};
+export type TokenList<CanonicalToken extends string = string> =
+	& PassthroughTokenList
+	& {
+		readonly [Key in TokenListKey<CanonicalToken>]:
+			Key extends SymbolIterator
+				? () => TokenListIterator<CanonicalToken>
+				: boolean;
+	};
 
 interface TokenListAlias<CanonicalToken extends string> {
 	readonly fromAlias: string;
@@ -101,7 +105,7 @@ export class TokenListParser<
 	private readonly aliases: ReadonlyMap<string, CanonicalToken>;
 
 	constructor(
-		readonly canonicalTokens: readonly CanonicalToken[],
+		readonly canonicalTokens: readonly CanonicalToken[] = [],
 		options?: TokenListParserOptions<TokenAlias>
 	) {
 		this.aliases = new Map(

package/src/lib/dom/query.ts

@@ -3,7 +3,7 @@ import type {
 	KnownAttributeLocalNamedElement,
 	LocalNamedElement,
 } from '@getodk/common/types/dom.ts';
-import type { SelectElement } from '../../body/control/select/SelectDefinition';
+import type { SelectElement } from '../../parse/body/control/select/SelectDefinition';
 
 const hintLookup = new ScopedElementLookup(':scope > hint', 'hint');
 const itemLookup = new ScopedElementLookup(':scope > item', 'item');

package/src/lib/reactivity/createComputedExpression.ts

@@ -2,16 +2,18 @@ import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
 import type { XFormsXPathEvaluator } from '@getodk/xpath';
 import type { Accessor } from 'solid-js';
 import { createMemo } from 'solid-js';
+import type { EvaluationContext } from '../../instance/internal-api/EvaluationContext.ts';
+import type { SubscribableDependency } from '../../instance/internal-api/SubscribableDependency.ts';
 import type {
 	DependentExpression,
 	DependentExpressionResultType,
-} from '../../expression/DependentExpression.ts';
-import type { EvaluationContext } from '../../instance/internal-api/EvaluationContext.ts';
-import type { SubscribableDependency } from '../../instance/internal-api/SubscribableDependency.ts';
+} from '../../parse/expression/abstract/DependentExpression.ts';
+import { isConstantExpression } from '../../parse/xpath/semantic-analysis.ts';
 
 interface ComputedExpressionResults {
 	readonly boolean: boolean;
 	readonly nodes: Node[];
+	readonly number: number;
 	readonly string: string;
 }
 
@@ -44,6 +46,11 @@ const expressionEvaluator = <Type extends DependentExpressionResultType>(
 				return evaluator.evaluateNodes(expression, options);
 			}) as ExpressionEvaluator<Type>;
 
+		case 'number':
+			return (() => {
+				return evaluator.evaluateNumber(expression, options);
+			}) as ExpressionEvaluator<Type>;
+
 		case 'string':
 			return (() => {
 				return evaluator.evaluateString(expression, options);
@@ -54,26 +61,19 @@ const expressionEvaluator = <Type extends DependentExpressionResultType>(
 	}
 };
 
-/**
- * Determines if an XPath expression will always produce the same value.
- *
- * @todo There are quite a few more cases than this, and it also likely belongs
- * in another `lib` module.
- */
-const isConstantExpression = (expression: string): boolean => {
-	const normalized = expression.replaceAll(/\s/g, '');
-
-	return normalized === 'true()' || normalized === 'false()';
-};
-
 // prettier-ignore
 type ComputedExpression<Type extends DependentExpressionResultType> = Accessor<
 	EvaluatedExpression<Type>
 >;
 
+interface CreateComputedExpressionOptions {
+	readonly arbitraryDependencies?: readonly SubscribableDependency[];
+}
+
 export const createComputedExpression = <Type extends DependentExpressionResultType>(
 	context: EvaluationContext,
-	dependentExpression: DependentExpression<Type>
+	dependentExpression: DependentExpression<Type>,
+	options: CreateComputedExpressionOptions = {}
 ): ComputedExpression<Type> => {
 	const { contextNode, evaluator, root, scope } = context;
 	const { expression, isTranslated, resultType } = dependentExpression;
@@ -85,26 +85,24 @@ export const createComputedExpression = <Type extends DependentExpressionResultT
 			return createMemo(evaluateExpression);
 		}
 
+		const { arbitraryDependencies = [] } = options;
+
 		const getReferencedDependencies = createMemo(() => {
 			return dependencyReferences.flatMap((reference) => {
 				return context.getSubscribableDependenciesByReference(reference) ?? [];
 			});
 		});
 
-		let getDependencies: Accessor<readonly SubscribableDependency[]>;
+		return createMemo(() => {
+			if (isTranslated) {
+				root.subscribe();
+			}
 
-		if (isTranslated) {
-			getDependencies = createMemo(() => {
-				return [root, ...getReferencedDependencies()];
+			arbitraryDependencies.forEach((dependency) => {
+				dependency.subscribe();
 			});
-		} else {
-			getDependencies = getReferencedDependencies;
-		}
-
-		return createMemo(() => {
-			const dependencies = getDependencies();
 
-			dependencies.forEach((dependency) => {
+			getReferencedDependencies().forEach((dependency) => {
 				dependency.subscribe();
 			});
 

package/src/lib/reactivity/createNoteReadonlyThunk.ts

@@ -0,0 +1,33 @@
+import type { Accessor } from 'solid-js';
+import type { EvaluationContext } from '../../instance/internal-api/EvaluationContext.ts';
+import type { BindComputationExpression } from '../../parse/expression/BindComputationExpression.ts';
+import { createComputedExpression } from './createComputedExpression.ts';
+
+export const createNoteReadonlyThunk = (
+	context: EvaluationContext,
+	readonlyDefinition: BindComputationExpression<'readonly'>
+): Accessor<true> => {
+	if (!readonlyDefinition.isConstantTruthyExpression()) {
+		throw new Error('Expected a static readonly expression');
+	}
+
+	let result = true;
+
+	if (import.meta.env.DEV) {
+		const { expression } = readonlyDefinition;
+
+		if (readonlyDefinition.dependencyReferences.size > 0) {
+			throw new Error(`Expected expression ${expression} to have no dependencies`);
+		}
+
+		const computedExpression = createComputedExpression(context, readonlyDefinition);
+
+		result = computedExpression();
+
+		if (result !== true) {
+			throw new Error(`Expected expression ${readonlyDefinition.expression} to return true`);
+		}
+	}
+
+	return () => result;
+};

package/src/lib/reactivity/createSelectItems.ts

@@ -2,8 +2,7 @@ import { UpsertableMap } from '@getodk/common/lib/collections/UpsertableMap.ts';
 import type { XFormsXPathEvaluator } from '@getodk/xpath';
 import type { Accessor } from 'solid-js';
 import { createMemo } from 'solid-js';
-import type { ItemDefinition } from '../../body/control/select/ItemDefinition.ts';
-import type { ItemsetDefinition } from '../../body/control/select/ItemsetDefinition.ts';
+import type { TextRange as ClientTextRange } from '../../client/TextRange.ts';
 import type { SelectItem } from '../../index.ts';
 import type { SelectField } from '../../instance/SelectField.ts';
 import type {
@@ -11,20 +10,33 @@ import type {
 	EvaluationContextRoot,
 } from '../../instance/internal-api/EvaluationContext.ts';
 import type { SubscribableDependency } from '../../instance/internal-api/SubscribableDependency.ts';
-import type { TextRange } from '../../instance/text/TextRange.ts';
+import { TextChunk } from '../../instance/text/TextChunk.ts';
+import { TextRange } from '../../instance/text/TextRange.ts';
+import type { ItemDefinition } from '../../parse/body/control/select/ItemDefinition.ts';
+import type { ItemsetDefinition } from '../../parse/body/control/select/ItemsetDefinition.ts';
 import { createComputedExpression } from './createComputedExpression.ts';
 import type { ReactiveScope } from './scope.ts';
 import { createTextRange } from './text/createTextRange.ts';
 
+type DerivedItemLabel = ClientTextRange<'item-label', 'form-derived'>;
+
+const derivedItemLabel = (context: EvaluationContext, value: string): DerivedItemLabel => {
+	const chunk = new TextChunk(context.root, 'literal', value);
+
+	return new TextRange('form-derived', 'item-label', [chunk]);
+};
+
 const createSelectItemLabel = (
 	context: EvaluationContext,
 	definition: ItemDefinition
-): Accessor<TextRange<'label'>> => {
+): Accessor<ClientTextRange<'item-label'>> => {
 	const { label, value } = definition;
 
-	return createTextRange(context, 'label', label, {
-		fallbackValue: value,
-	});
+	if (label == null) {
+		return () => derivedItemLabel(context, value);
+	}
+
+	return createTextRange(context, 'item-label', label);
 };
 
 const createTranslatedStaticSelectItems = (
@@ -73,25 +85,20 @@ const createSelectItemsetItemLabel = (
 	context: EvaluationContext,
 	definition: ItemsetDefinition,
 	itemValue: Accessor<string>
-): Accessor<TextRange<'label'>> => {
+): Accessor<ClientTextRange<'item-label'>> => {
 	const { label } = definition;
 
 	if (label == null) {
 		return createMemo(() => {
-			const value = itemValue();
-			const staticValueLabel = createTextRange(context, 'label', label, {
-				fallbackValue: value,
-			});
-
-			return staticValueLabel();
+			return derivedItemLabel(context, itemValue());
 		});
 	}
 
-	return createTextRange(context, 'label', label);
+	return createTextRange(context, 'item-label', label);
 };
 
 interface ItemsetItem {
-	label(): TextRange<'label'>;
+	label(): ClientTextRange<'item-label'>;
 	value(): string;
 }
 

package/src/lib/reactivity/createValueState.ts

@@ -1,8 +1,8 @@
 import { createComputed, createMemo, createSignal, untrack } from 'solid-js';
-import type { DependentExpression } from '../../expression/DependentExpression.ts';
 import type { SubscribableDependency } from '../../instance/internal-api/SubscribableDependency.ts';
 import type { ValueContext } from '../../instance/internal-api/ValueContext.ts';
-import type { BindComputation } from '../../model/BindComputation.ts';
+import type { BindComputationExpression } from '../../parse/expression/BindComputationExpression.ts';
+import type { DependentExpression } from '../../parse/expression/abstract/DependentExpression.ts';
 import { createComputedExpression } from './createComputedExpression.ts';
 import type { SimpleAtomicState, SimpleAtomicStateSetter } from './types.ts';
 
@@ -209,7 +209,7 @@ const guardDownstreamReadonlyWrites = <RuntimeValue>(
 const createCalculation = <RuntimeValue>(
 	context: ValueContext<RuntimeValue>,
 	setValue: SimpleAtomicStateSetter<RuntimeValue>,
-	calculateDefinition: BindComputation<'calculate'>
+	calculateDefinition: BindComputationExpression<'calculate'>
 ): void => {
 	context.scope.runTask(() => {
 		const calculate = createComputedExpression(context, calculateDefinition);

package/src/lib/reactivity/node-state/createSharedNodeState.ts

@@ -31,7 +31,7 @@ export interface SharedNodeState<Spec extends StateSpec> {
 	readonly setProperty: SetEnginePropertyState<Spec>;
 }
 
-interface SharedNodeStateOptions<
+export interface SharedNodeStateOptions<
 	Factory extends OpaqueReactiveObjectFactory,
 	Spec extends StateSpec,
 > {

package/src/lib/reactivity/node-state/createSpecifiedState.ts

@@ -80,7 +80,7 @@ export type ComputedPropertySpec<T> = Accessor<T>;
 /**
  * @see {@link StaticPropertySpec}
  */
-// eslint-disable-next-line @typescript-eslint/ban-types, @typescript-eslint/no-explicit-any
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type, @typescript-eslint/no-explicit-any
 type NonStaticValue = Function | Signal<any> | SimpleAtomicState<any>;
 
 /**

package/src/lib/reactivity/text/createFieldHint.ts

@@ -1,16 +1,18 @@
 import { type Accessor } from 'solid-js';
+import type { TextRange } from '../../../client/TextRange.ts';
 import type { EvaluationContext } from '../../../instance/internal-api/EvaluationContext.ts';
-import { TextRange } from '../../../instance/text/TextRange.ts';
-import type { ValueNodeDefinition } from '../../../model/ValueNodeDefinition.ts';
+import type { LeafNodeDefinition } from '../../../parse/model/LeafNodeDefinition.ts';
 import { createTextRange } from './createTextRange.ts';
 
 export const createFieldHint = (
 	context: EvaluationContext,
-	definition: ValueNodeDefinition
-): Accessor<TextRange<'hint'> | null> => {
+	definition: LeafNodeDefinition
+): Accessor<TextRange<'hint', 'form'> | null> => {
 	const hintDefinition = definition.bodyElement?.hint ?? null;
 
-	return createTextRange(context, 'hint', hintDefinition, {
-		fallbackValue: null,
-	});
+	if (hintDefinition == null) {
+		return () => null;
+	}
+
+	return createTextRange(context, 'hint', hintDefinition);
 };

package/src/lib/reactivity/text/createNodeLabel.ts

@@ -1,16 +1,18 @@
 import { type Accessor } from 'solid-js';
+import type { TextRange } from '../../../client/TextRange.ts';
 import type { EvaluationContext } from '../../../instance/internal-api/EvaluationContext.ts';
-import { TextRange } from '../../../instance/text/TextRange.ts';
-import type { AnyNodeDefinition } from '../../../model/NodeDefinition.ts';
+import type { AnyNodeDefinition } from '../../../parse/model/NodeDefinition.ts';
 import { createTextRange } from './createTextRange.ts';
 
 export const createNodeLabel = (
 	context: EvaluationContext,
 	definition: AnyNodeDefinition
-): Accessor<TextRange<'label'> | null> => {
+): Accessor<TextRange<'label', 'form'> | null> => {
 	const labelDefinition = definition.bodyElement?.label ?? null;
 
-	return createTextRange(context, 'label', labelDefinition, {
-		fallbackValue: null,
-	});
+	if (labelDefinition == null) {
+		return () => null;
+	}
+
+	return createTextRange(context, 'label', labelDefinition);
 };

package/src/lib/reactivity/text/createNoteText.ts

@@ -0,0 +1,72 @@
+import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
+import type { Accessor } from 'solid-js';
+import type { TextRange } from '../../../client/TextRange.ts';
+import type { EvaluationContext } from '../../../instance/internal-api/EvaluationContext.ts';
+import type { NoteTextDefinition } from '../../../parse/model/NoteNodeDefinition.ts';
+import { createTextRange } from './createTextRange.ts';
+
+// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+export type NoteTextRole = 'label' | 'hint';
+
+export type ComputedNoteText<Role extends NoteTextRole = NoteTextRole> = Accessor<
+	TextRange<Role, 'form'>
+>;
+
+interface BaseNoteText {
+	readonly role: NoteTextRole;
+	readonly label: ComputedNoteText<'label'> | null;
+	readonly hint: ComputedNoteText<'hint'> | null;
+}
+
+interface LabelNoteText extends BaseNoteText {
+	readonly role: 'label';
+	readonly label: ComputedNoteText<'label'>;
+	readonly hint: null;
+}
+
+interface HintNoteText extends BaseNoteText {
+	readonly role: 'hint';
+	readonly label: null;
+	readonly hint: ComputedNoteText<'hint'>;
+}
+
+// prettier-ignore
+export type NoteTextComputation =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| LabelNoteText
+	| HintNoteText;
+
+export const createNoteText = (
+	context: EvaluationContext,
+	noteTextDefinition: NoteTextDefinition
+): NoteTextComputation => {
+	const { scope } = context;
+	const { role } = noteTextDefinition;
+
+	return scope.runTask(() => {
+		switch (role) {
+			case 'label': {
+				const label = createTextRange(context, role, noteTextDefinition);
+
+				return {
+					role,
+					label,
+					hint: null,
+				};
+			}
+
+			case 'hint': {
+				const hint = createTextRange(context, role, noteTextDefinition);
+
+				return {
+					role,
+					label: null,
+					hint,
+				};
+			}
+
+			default:
+				throw new UnreachableError(noteTextDefinition);
+		}
+	});
+};

package/src/lib/reactivity/text/createTextRange.ts

@@ -1,23 +1,13 @@
-import type { CollectionValues } from '@getodk/common/types/collections/CollectionValues.ts';
-import { createMemo, type Accessor } from 'solid-js';
-import type {
-	TextElementChild,
-	TextElementDefinition,
-} from '../../../body/text/TextElementDefinition.ts';
-import type { TextElementReferencePart } from '../../../body/text/TextElementReferencePart.ts';
-import type { TextChunkSource } from '../../../client/TextRange.ts';
+import type { Accessor } from 'solid-js';
+import { createMemo } from 'solid-js';
+import type { TextChunkSource, TextRole } from '../../../client/TextRange.ts';
 import type { EvaluationContext } from '../../../instance/internal-api/EvaluationContext.ts';
 import { TextChunk } from '../../../instance/text/TextChunk.ts';
-import { TextRange, type TextRole } from '../../../instance/text/TextRange.ts';
+import { TextRange } from '../../../instance/text/TextRange.ts';
+import type { AnyTextChunkExpression } from '../../../parse/expression/abstract/TextChunkExpression.ts';
+import type { TextRangeDefinition } from '../../../parse/text/abstract/TextRangeDefinition.ts';
 import { createComputedExpression } from '../createComputedExpression.ts';
 
-// prettier-ignore
-type TextSources =
-	| readonly [TextElementReferencePart]
-	| readonly TextElementChild[];
-
-type TextSource = CollectionValues<TextSources>;
-
 interface TextChunkComputation {
 	readonly source: TextChunkSource;
 	readonly getText: Accessor<string>;
@@ -25,21 +15,20 @@ interface TextChunkComputation {
 
 const createComputedTextChunk = (
 	context: EvaluationContext,
-	textSource: TextSource
+	textSource: AnyTextChunkExpression
 ): TextChunkComputation => {
-	const { type } = textSource;
+	const { source } = textSource;
 
-	if (type === 'static') {
+	if (source === 'literal') {
 		const { stringValue } = textSource;
 
 		return {
-			source: type,
+			source,
 			getText: () => stringValue,
 		};
 	}
 
 	return context.scope.runTask(() => {
-		const source: TextChunkSource = type === 'reference' ? 'itext' : type;
 		const getText = createComputedExpression(context, textSource);
 
 		return {
@@ -51,7 +40,7 @@ const createComputedTextChunk = (
 
 const createTextChunks = (
 	context: EvaluationContext,
-	textSources: TextSources
+	textSources: readonly AnyTextChunkExpression[]
 ): Accessor<readonly TextChunk[]> => {
 	return context.scope.runTask(() => {
 		const { root } = context;
@@ -67,45 +56,7 @@ const createTextChunks = (
 	});
 };
 
-interface CreateTextRangeOptions<FallbackValue extends string | null> {
-	readonly fallbackValue?: FallbackValue;
-}
-
-// prettier-ignore
-type ComputedTextRange<
-	Role extends TextRole,
-	Definition extends TextElementDefinition<Role> | null,
-	FallbackValue extends string | null
-> = Accessor<
-	Definition extends null
-		?  FallbackValue extends null
-			? TextRange<Role> | null
-			: TextRange<Role>
-		: TextRange<Role>
->;
-
-// prettier-ignore
-type FallbackTextRange<
-	Role extends TextRole,
-	FallbackValue extends string | null
-> =
-	FallbackValue extends null
-		? TextRange<Role> | null
-		: TextRange<Role>;
-
-const createFallbackTextRange = <Role extends TextRole, FallbackValue extends string | null>(
-	context: EvaluationContext,
-	role: Role,
-	fallbackValue: FallbackValue
-): FallbackTextRange<Role, FallbackValue> => {
-	if (fallbackValue == null) {
-		return null as FallbackTextRange<Role, FallbackValue>;
-	}
-
-	const staticChunk = new TextChunk(context.root, 'static', fallbackValue);
-
-	return new TextRange(role, [staticChunk]);
-};
+type ComputedFormTextRange<Role extends TextRole> = Accessor<TextRange<Role, 'form'>>;
 
 /**
  * Creates a text range (e.g. label or hint) from the provided definition,
@@ -116,40 +67,16 @@ const createFallbackTextRange = <Role extends TextRole, FallbackValue extends st
  *
  * @todo This does not yet handle itext translations **with** outputs!
  */
-export const createTextRange = <
-	Role extends TextRole,
-	Definition extends TextElementDefinition<Role> | null,
-	FallbackValue extends string | null = null,
->(
+export const createTextRange = <Role extends TextRole>(
 	context: EvaluationContext,
 	role: Role,
-	definition: Definition,
-	options?: CreateTextRangeOptions<FallbackValue>
-): ComputedTextRange<Role, Definition, FallbackValue> => {
+	definition: TextRangeDefinition<Role>
+): ComputedFormTextRange<Role> => {
 	return context.scope.runTask(() => {
-		if (definition == null) {
-			const textRange = createFallbackTextRange(
-				context,
-				role,
-				options?.fallbackValue ?? (null as FallbackValue)
-			);
-			const getTextRange = () => textRange;
-
-			return getTextRange as ComputedTextRange<Role, Definition, FallbackValue>;
-		}
-
-		const { children, referenceExpression } = definition;
-
-		let getTextChunks: Accessor<readonly TextChunk[]>;
-
-		if (referenceExpression == null) {
-			getTextChunks = createTextChunks(context, children);
-		} else {
-			getTextChunks = createTextChunks(context, [referenceExpression]);
-		}
+		const getTextChunks = createTextChunks(context, definition.chunks);
 
 		return createMemo(() => {
-			return new TextRange(role, getTextChunks());
+			return new TextRange('form', role, getTextChunks());
 		});
 	});
 };

package/src/lib/reactivity/validation/createAggregatedViolations.ts

@@ -0,0 +1,75 @@
+import { createMemo } from 'solid-js';
+import type { OpaqueReactiveObjectFactory } from '../../../client/OpaqueReactiveObjectFactory.ts';
+import type {
+	AncestorNodeValidationState,
+	DescendantNodeViolationReference,
+} from '../../../client/validation.ts';
+import type { AnyParentNode } from '../../../instance/hierarchy.ts';
+import type { ValidationContext } from '../../../instance/internal-api/ValidationContext.ts';
+import { createSharedNodeState } from '../node-state/createSharedNodeState.ts';
+
+const violationReference = (node: ValidationContext): DescendantNodeViolationReference | null => {
+	const violation = node.getViolation();
+
+	if (violation == null) {
+		return null;
+	}
+
+	const { nodeId } = node;
+
+	return {
+		nodeId,
+		get reference() {
+			return node.currentState.reference;
+		},
+		violation,
+	};
+};
+
+const collectViolationReferences = (
+	context: AnyParentNode
+): readonly DescendantNodeViolationReference[] => {
+	return context.getChildren().flatMap((child) => {
+		switch (child.nodeType) {
+			case 'model-value':
+			case 'note':
+			case 'string':
+			case 'select':
+			case 'range':
+			case 'rank':
+			case 'trigger':
+			case 'upload': {
+				const reference = violationReference(child);
+
+				if (reference == null) {
+					return [];
+				}
+
+				return [reference];
+			}
+
+			default:
+				return collectViolationReferences(child);
+		}
+	});
+};
+
+interface AggregatedViolationsOptions {
+	readonly clientStateFactory: OpaqueReactiveObjectFactory<AncestorNodeValidationState>;
+}
+
+export const createAggregatedViolations = (
+	context: AnyParentNode,
+	options: AggregatedViolationsOptions
+): AncestorNodeValidationState => {
+	const { scope } = context;
+
+	return scope.runTask(() => {
+		const violations = createMemo(() => {
+			return collectViolationReferences(context);
+		});
+		const spec = { violations };
+
+		return createSharedNodeState(scope, spec, options).currentState;
+	});
+};