@getodk/xforms-engine 0.15.0 → 0.16.0

package/src/parse/model/ModelActionMap.ts

@@ -0,0 +1,37 @@
+import { ActionDefinition } from './ActionDefinition.ts';
+import { XFORM_EVENT } from './Event.ts';
+import type { ModelDefinition } from './ModelDefinition.ts';
+
+const REPEAT_REGEX = /(\[[^\]]*\])/gm;
+
+export class ModelActionMap extends Map<string, ActionDefinition> {
+	static fromModel(model: ModelDefinition): ModelActionMap {
+		return new this(model);
+	}
+
+	static getKey(ref: string): string {
+		return ref.replace(REPEAT_REGEX, '');
+	}
+
+	protected constructor(model: ModelDefinition) {
+		super(
+			model.form.xformDOM.setValues.map((setValueElement) => {
+				const action = new ActionDefinition(model, setValueElement);
+				if (action.events.includes(XFORM_EVENT.odkNewRepeat)) {
+					throw new Error('Model contains "setvalue" element with "odk-new-repeat" event');
+				}
+				const key = ModelActionMap.getKey(action.ref);
+				return [key, action];
+			})
+		);
+	}
+
+	override get(ref: string): ActionDefinition | undefined {
+		return super.get(ModelActionMap.getKey(ref));
+	}
+
+	add(action: ActionDefinition) {
+		const key = ModelActionMap.getKey(action.ref);
+		this.set(key, action);
+	}
+}

package/src/parse/model/ModelDefinition.ts

@@ -6,6 +6,7 @@ import { parseStaticDocumentFromDOMSubtree } from '../shared/parseStaticDocument
 import type { XFormDefinition } from '../XFormDefinition.ts';
 import { generateItextChunks, type ChunkExpressionsByItextId } from './generateItextChunks.ts';
 import { ItextTranslationsDefinition } from './ItextTranslationsDefinition.ts';
+import { ModelActionMap } from './ModelActionMap.ts';
 import { ModelBindMap } from './ModelBindMap.ts';
 import type { AnyNodeDefinition } from './NodeDefinition.ts';
 import type { NodeDefinitionMap } from './nodeDefinitionMap.ts';
@@ -13,18 +14,23 @@ import { nodeDefinitionMap } from './nodeDefinitionMap.ts';
 import { RootDefinition } from './RootDefinition.ts';
 import { SubmissionDefinition } from './SubmissionDefinition.ts';
 
+type XformsRevalidateListener = () => void;
+
 export class ModelDefinition {
 	readonly binds: ModelBindMap;
+	readonly actions: ModelActionMap;
 	readonly root: RootDefinition;
 	readonly nodes: NodeDefinitionMap;
 	readonly instance: StaticDocument;
 	readonly itextTranslations: ItextTranslationsDefinition;
 	readonly itextChunks: Map<string, ChunkExpressionsByItextId>;
+	readonly xformsRevalidateListeners: Map<string, XformsRevalidateListener>;
 
 	constructor(readonly form: XFormDefinition) {
 		const submission = new SubmissionDefinition(form.xformDOM);
 
 		this.binds = ModelBindMap.fromModel(this);
+		this.actions = ModelActionMap.fromModel(this);
 		this.instance = parseStaticDocumentFromDOMSubtree(form.xformDOM.primaryInstanceRoot, {
 			nodesetPrefix: '/',
 		});
@@ -32,6 +38,7 @@ export class ModelDefinition {
 		this.nodes = nodeDefinitionMap(this.root);
 		this.itextTranslations = ItextTranslationsDefinition.from(form.xformDOM);
 		this.itextChunks = generateItextChunks(form.xformDOM.itextTranslationElements);
+		this.xformsRevalidateListeners = new Map();
 	}
 
 	getNodeDefinition(nodeset: string): AnyNodeDefinition {
@@ -54,10 +61,12 @@ export class ModelDefinition {
 		return definition;
 	}
 
-	toJSON() {
-		const { form, ...rest } = this;
+	registerXformsRevalidateListener(ref: string, listener: XformsRevalidateListener) {
+		this.xformsRevalidateListeners.set(ref, listener);
+	}
 
-		return rest;
+	triggerXformsRevalidateListeners() {
+		this.xformsRevalidateListeners.forEach((listener: XformsRevalidateListener) => listener());
 	}
 
 	getTranslationChunks(
@@ -67,4 +76,10 @@ export class ModelDefinition {
 		const languageMap = this.itextChunks.get(activeLanguage.language);
 		return languageMap?.get(itextId) ?? [];
 	}
+
+	toJSON() {
+		const { form, ...rest } = this;
+
+		return rest;
+	}
 }

package/src/parse/model/NoteNodeDefinition.ts

@@ -9,6 +9,7 @@ import type { HintDefinition } from '../text/HintDefinition.ts';
 import type { LabelDefinition } from '../text/LabelDefinition.ts';
 import type { BindDefinition } from './BindDefinition.ts';
 import { LeafNodeDefinition } from './LeafNodeDefinition.ts';
+import type { ModelDefinition } from './ModelDefinition.ts';
 import type { ParentNodeDefinition } from './NodeDefinition.ts';
 
 // prettier-ignore
@@ -41,6 +42,7 @@ export type NoteTextDefinition =
  */
 export class NoteNodeDefinition<V extends ValueType = ValueType> extends LeafNodeDefinition<V> {
 	static from<V extends ValueType>(
+		model: ModelDefinition,
 		parent: ParentNodeDefinition,
 		bind: BindDefinition<V>,
 		bodyElement: AnyBodyElementDefinition | null,
@@ -57,16 +59,17 @@ export class NoteNodeDefinition<V extends ValueType = ValueType> extends LeafNod
 			return null;
 		}
 
-		return new this(parent, bind, bodyElement, noteTextDefinition, node);
+		return new this(model, parent, bind, bodyElement, noteTextDefinition, node);
 	}
 
 	constructor(
+		model: ModelDefinition,
 		parent: ParentNodeDefinition,
 		override readonly bind: NoteBindDefinition<V>,
 		override readonly bodyElement: InputControlDefinition,
 		readonly noteTextDefinition: NoteTextDefinition,
 		template: StaticLeafElement
 	) {
-		super(parent, bind, bodyElement, template);
+		super(model, parent, bind, bodyElement, template);
 	}
 }

package/src/parse/model/RangeNodeDefinition.ts

@@ -9,6 +9,7 @@ import type {
 } from '../body/control/RangeControlDefinition.ts';
 import type { BindDefinition } from './BindDefinition.ts';
 import { LeafNodeDefinition } from './LeafNodeDefinition.ts';
+import type { ModelDefinition } from './ModelDefinition.ts';
 import type { ParentNodeDefinition } from './NodeDefinition.ts';
 
 const RANGE_VALUE_TYPES = ['decimal', 'int'] as const;
@@ -89,6 +90,7 @@ export class RangeNodeDefinition<V extends RangeValueType = RangeValueType>
 	implements RangeLeafNodeDefinition<V>
 {
 	static from<V extends ValueType>(
+		model: ModelDefinition,
 		parent: ParentNodeDefinition,
 		bind: BindDefinition<V>,
 		bodyElement: RangeControlDefinition,
@@ -96,18 +98,19 @@ export class RangeNodeDefinition<V extends RangeValueType = RangeValueType>
 	): RangeNodeDefinition<Extract<V, RangeValueType>> {
 		assertRangeBindDefinition(bind);
 
-		return new this(parent, bind, bodyElement, node);
+		return new this(model, parent, bind, bodyElement, node);
 	}
 
 	readonly bounds: RangeNodeBoundsDefinition<V>;
 
 	private constructor(
+		model: ModelDefinition,
 		parent: ParentNodeDefinition,
 		override readonly bind: BindDefinition<V>,
 		override readonly bodyElement: RangeControlDefinition,
 		node: StaticLeafElement
 	) {
-		super(parent, bind, bodyElement, node);
+		super(model, parent, bind, bodyElement, node);
 
 		this.bounds = RangeNodeBoundsDefinition.from(bodyElement.bounds, bind);
 	}

package/src/parse/model/RootDefinition.ts

@@ -1,8 +1,9 @@
 import type { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
 import { NamespaceDeclarationMap } from '../../lib/names/NamespaceDeclarationMap.ts';
 import { QualifiedName } from '../../lib/names/QualifiedName.ts';
-import type { BodyClassList } from '../body/BodyDefinition.ts';
+import type { AnyBodyElementDefinition, BodyClassList } from '../body/BodyDefinition.ts';
 import type { XFormDefinition } from '../XFormDefinition.ts';
+import { ActionDefinition } from './ActionDefinition.ts';
 import { AttributeDefinitionMap } from './AttributeDefinitionMap.ts';
 import { GroupDefinition } from './GroupDefinition.ts';
 import { LeafNodeDefinition } from './LeafNodeDefinition.ts';
@@ -56,6 +57,19 @@ export class RootDefinition extends NodeDefinition<'root'> {
 		this.children = this.buildSubtree(this, template);
 	}
 
+	private mapActions(bodyElement: AnyBodyElementDefinition) {
+		const source = bodyElement.reference;
+		if (!source) {
+			return;
+		}
+		for (const child of bodyElement.element.children) {
+			if (child.nodeName === 'setvalue') {
+				const action = new ActionDefinition(this.model, child, source);
+				this.model.actions.add(action);
+			}
+		}
+	}
+
 	buildSubtree(parent: ParentNodeDefinition, node: StaticElement): readonly ChildNodeDefinition[] {
 		const { form, model } = this;
 		const { body } = form;
@@ -86,6 +100,10 @@ export class RootDefinition extends NodeDefinition<'root'> {
 			const bodyElement = body.getBodyElement(nodeset);
 			const [firstChild, ...restChildren] = children;
 
+			if (bodyElement) {
+				this.mapActions(bodyElement);
+			}
+
 			if (bodyElement?.type === 'repeat') {
 				return RepeatDefinition.from(model, parent, bind, bodyElement, children);
 			}
@@ -98,12 +116,12 @@ export class RootDefinition extends NodeDefinition<'root'> {
 
 			if (element.isLeafElement()) {
 				if (bodyElement?.type === 'range') {
-					return RangeNodeDefinition.from(parent, bind, bodyElement, element);
+					return RangeNodeDefinition.from(model, parent, bind, bodyElement, element);
 				}
 
 				return (
-					NoteNodeDefinition.from(parent, bind, bodyElement, element) ??
-					new LeafNodeDefinition(parent, bind, bodyElement, element)
+					NoteNodeDefinition.from(model, parent, bind, bodyElement, element) ??
+					new LeafNodeDefinition(model, parent, bind, bodyElement, element)
 				);
 			}
 

package/dist/lib/reactivity/createAttributeValueState.d.ts

@@ -1,15 +0,0 @@
-import { AttributeContext } from '../../instance/internal-api/AttributeContext.ts';
-import { SimpleAtomicState } from './types.ts';
-export type InstanceValueState = SimpleAtomicState<string>;
-/**
- * Provides a consistent interface for value nodes of any type which:
- *
- * - derives initial state from either an existing instance (e.g. for edits) or
- *   the node's definition (e.g. initializing a new instance)
- * - decodes current primary instance state into the value node's runtime type
- * - encodes updated runtime values to store updated instance state
- * - initializes reactive computation of `calculate` bind expressions for those
- *   nodes defined with one
- * - prevents downstream writes to nodes in a readonly state
- */
-export declare const createAttributeValueState: (context: AttributeContext) => InstanceValueState;

package/src/lib/reactivity/createAttributeValueState.ts

@@ -1,189 +0,0 @@
-import type { Signal } from 'solid-js';
-import { createComputed, createMemo, createSignal, untrack } from 'solid-js';
-import type { AttributeContext } from '../../instance/internal-api/AttributeContext.ts';
-import type { BindComputationExpression } from '../../parse/expression/BindComputationExpression.ts';
-import { createComputedExpression } from './createComputedExpression.ts';
-import type { SimpleAtomicState, SimpleAtomicStateSetter } from './types.ts';
-
-const isInstanceFirstLoad = (context: AttributeContext) => {
-	return context.rootDocument.initializationMode === 'create';
-};
-
-/**
- * Special case, does not correspond to any event.
- *
- * @see {@link shouldPreloadUID}
- */
-const isEditInitialLoad = (context: AttributeContext) => {
-	return context.rootDocument.initializationMode === 'edit';
-};
-
-const getInitialValue = (context: AttributeContext): string => {
-	const sourceNode = context.instanceNode ?? context.definition.template;
-
-	return context.decodeInstanceValue(sourceNode.value);
-};
-
-type BaseValueState = Signal<string>;
-
-type RelevantValueState = SimpleAtomicState<string>;
-
-/**
- * Wraps {@link baseValueState} in a signal-like interface which:
- *
- * - produces a blank value for nodes ({@link context}) in a non-relevant state
- * - persists, and restores, the most recent non-blank value state when a
- *   node/context's relevance is restored
- */
-const createRelevantValueState = (
-	context: AttributeContext,
-	baseValueState: BaseValueState
-): RelevantValueState => {
-	return context.scope.runTask(() => {
-		const [getRelevantValue, setValue] = baseValueState;
-
-		const getValue = createMemo(() => {
-			if (context.isRelevant()) {
-				return getRelevantValue();
-			}
-
-			return '';
-		});
-
-		return [getValue, setValue];
-	});
-};
-
-/**
- * For fields with a `readonly` bind expression, prevent downstream
- * (client/user) writes when the field is in a `readonly` state.
- */
-const guardDownstreamReadonlyWrites = (
-	context: AttributeContext,
-	baseState: SimpleAtomicState<string>
-): SimpleAtomicState<string> => {
-	const { readonly } = context.definition.bind;
-
-	if (readonly.isDefaultExpression) {
-		return baseState;
-	}
-
-	const [getValue, baseSetValue] = baseState;
-
-	const setValue: SimpleAtomicStateSetter<string> = (value) => {
-		if (context.isReadonly()) {
-			const reference = untrack(() => context.contextReference());
-
-			throw new Error(`Cannot write to readonly field: ${reference}`);
-		}
-
-		return baseSetValue(value);
-	};
-
-	return [getValue, setValue];
-};
-
-/**
- * Per {@link https://getodk.github.io/xforms-spec/#preload-attributes:~:text=concatenation%20of%20%E2%80%98uuid%3A%E2%80%99%20and%20uuid()}
- */
-const PRELOAD_UID_EXPRESSION = 'concat("uuid:", uuid())';
-
-/**
- * @todo It feels increasingly awkward to keep piling up preload stuff here, but it won't stay that way for long. In the meantime, this seems like the best way to express the cases where `preload="uid"` should be effective, i.e.:
- *
- * - When an instance is first loaded ({@link isInstanceFirstLoad})
- * - When an instance is initially loaded for editing ({@link isEditInitialLoad})
- */
-const shouldPreloadUID = (context: AttributeContext) => {
-	return isInstanceFirstLoad(context) || isEditInitialLoad(context);
-};
-
-/**
- * @todo This is a temporary one-off, until we support the full range of
- * {@link https://getodk.github.io/xforms-spec/#preload-attributes | preloads}.
- *
- * @todo ALSO, IMPORTANTLY(!): the **call site** for this function is
- * semantically where we would expect to trigger a
- * {@link https://getodk.github.io/xforms-spec/#event:odk-instance-first-load | odk-instance-first-load event},
- * _and compute_ preloads semantically associated with that event.
- */
-const setPreloadUIDValue = (context: AttributeContext, valueState: RelevantValueState): void => {
-	const { preload } = context.definition.bind;
-
-	if (preload?.type !== 'uid' || !shouldPreloadUID(context)) {
-		return;
-	}
-
-	const preloadUIDValue = context.evaluator.evaluateString(PRELOAD_UID_EXPRESSION, {
-		contextNode: context.contextNode,
-	});
-
-	const [, setValue] = valueState;
-
-	setValue(preloadUIDValue);
-};
-
-/**
- * Defines a reactive effect which writes the result of `calculate` bind
- * computations to the provided value setter, on initialization and any
- * subsequent reactive update.
- *
- * @see {@link setPreloadUIDValue} for important details about spec ordering of
- * events and computations.
- */
-const createCalculation = (
-	context: AttributeContext,
-	setRelevantValue: SimpleAtomicStateSetter<string>,
-	calculateDefinition: BindComputationExpression<'calculate'>
-): void => {
-	context.scope.runTask(() => {
-		const calculate = createComputedExpression(context, calculateDefinition, {
-			defaultValue: '',
-		});
-
-		createComputed(() => {
-			if (context.isAttached() && context.isRelevant()) {
-				const calculated = calculate();
-				const value = context.decodeInstanceValue(calculated);
-
-				setRelevantValue(value);
-			}
-		});
-	});
-};
-
-export type InstanceValueState = SimpleAtomicState<string>;
-
-/**
- * Provides a consistent interface for value nodes of any type which:
- *
- * - derives initial state from either an existing instance (e.g. for edits) or
- *   the node's definition (e.g. initializing a new instance)
- * - decodes current primary instance state into the value node's runtime type
- * - encodes updated runtime values to store updated instance state
- * - initializes reactive computation of `calculate` bind expressions for those
- *   nodes defined with one
- * - prevents downstream writes to nodes in a readonly state
- */
-export const createAttributeValueState = (context: AttributeContext): InstanceValueState => {
-	return context.scope.runTask(() => {
-		const initialValue = getInitialValue(context);
-		const baseValueState = createSignal(initialValue);
-		const relevantValueState = createRelevantValueState(context, baseValueState);
-
-		/**
-		 * @see {@link setPreloadUIDValue} for important details about spec ordering of events and computations.
-		 */
-		setPreloadUIDValue(context, relevantValueState);
-
-		const { calculate } = context.definition.bind;
-
-		if (calculate != null) {
-			const [, setValue] = relevantValueState;
-
-			createCalculation(context, setValue, calculate);
-		}
-
-		return guardDownstreamReadonlyWrites(context, relevantValueState);
-	});
-};