@getodk/xforms-engine 0.15.0 → 0.16.1

package/src/parse/model/ActionDefinition.ts

@@ -0,0 +1,70 @@
+import { isTextNode } from '@getodk/common/lib/dom/predicates.ts';
+import { ActionComputationExpression } from '../expression/ActionComputationExpression.ts';
+import { type XFormEvent, XFORM_EVENT } from './Event.ts';
+import type { ModelDefinition } from './ModelDefinition.ts';
+
+export class ActionDefinition {
+	static getRef(model: ModelDefinition, setValueElement: Element): string | null {
+		if (setValueElement.hasAttribute('ref')) {
+			return setValueElement.getAttribute('ref') ?? null;
+		}
+		if (setValueElement.hasAttribute('bind')) {
+			const bindId = setValueElement.getAttribute('bind');
+			const bindDefinition = Array.from(model.binds.values()).find((definition) => {
+				return definition.bindElement.getAttribute('id') === bindId;
+			});
+			return bindDefinition?.nodeset ?? null;
+		}
+		return null;
+	}
+
+	static getValue(element: Element): string {
+		if (element.hasAttribute('value')) {
+			// eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
+			return element.getAttribute('value') || "''";
+		}
+		if (element.firstChild && isTextNode(element.firstChild)) {
+			// use the text content as the literal value
+			return `'${element.firstChild.nodeValue}'`;
+		}
+		return "''";
+	}
+
+	static isKnownEvent = (event: XFormEvent): event is XFormEvent => {
+		return Object.values(XFORM_EVENT).includes(event);
+	};
+
+	static getEvents(element: Element): XFormEvent[] {
+		const events = element.getAttribute('event')?.split(' ') ?? [];
+		const unknownEvents = events.filter((event) => !this.isKnownEvent(event as XFormEvent));
+		if (unknownEvents.length) {
+			throw new Error(
+				`An action was registered for unsupported events: ${unknownEvents.join(', ')}`
+			);
+		}
+		return events as XFormEvent[];
+	}
+
+	readonly ref: string;
+	readonly events: XFormEvent[];
+	readonly computation: ActionComputationExpression<'string'>;
+	readonly source: string | undefined;
+
+	constructor(
+		model: ModelDefinition,
+		readonly element: Element,
+		source?: string
+	) {
+		const ref = ActionDefinition.getRef(model, element);
+		if (!ref) {
+			throw new Error(
+				'Invalid setvalue element - you must define either "ref" or "bind" attribute'
+			);
+		}
+		this.ref = ref;
+		this.events = ActionDefinition.getEvents(element);
+		const value = ActionDefinition.getValue(element);
+		this.computation = new ActionComputationExpression('string', value);
+		this.source = source;
+	}
+}

package/src/parse/model/AttributeDefinition.ts

@@ -7,6 +7,7 @@ import {
 import { QualifiedName } from '../../lib/names/QualifiedName.ts';
 import { escapeXMLText, serializeAttributeXML } from '../../lib/xml-serialization.ts';
 import type { BindDefinition } from './BindDefinition.ts';
+import type { ModelDefinition } from './ModelDefinition.ts';
 import { NodeDefinition } from './NodeDefinition.ts';
 import type { RootDefinition } from './RootDefinition.ts';
 
@@ -18,6 +19,7 @@ export class AttributeDefinition
 
 	readonly value: string;
 	readonly type = 'attribute';
+	readonly valueType = 'string';
 	readonly namespaceDeclarations: NamespaceDeclarationMap;
 	readonly bodyElement = null;
 	readonly root: RootDefinition;
@@ -29,7 +31,7 @@ export class AttributeDefinition
 	readonly qualifiedName: QualifiedName;
 
 	constructor(
-		root: RootDefinition,
+		readonly model: ModelDefinition,
 		bind: BindDefinition,
 		readonly template: StaticAttribute
 	) {
@@ -37,7 +39,7 @@ export class AttributeDefinition
 
 		const { value } = template;
 
-		this.root = root;
+		this.root = model.root;
 
 		this.value = value;
 		this.qualifiedName = template.qualifiedName;
@@ -55,4 +57,10 @@ export class AttributeDefinition
 	serializeAttributeXML(): string {
 		return this.serializedXML;
 	}
+
+	toJSON() {
+		const { bind, bodyElement, parent, root, ...rest } = this;
+
+		return rest;
+	}
 }

package/src/parse/model/AttributeDefinitionMap.ts

@@ -28,7 +28,7 @@ export class AttributeDefinitionMap extends Map<QualifiedName, AttributeDefiniti
 		const nonNamespaceAttributes = instanceNode.attributes.filter(isNonNamespaceAttribute);
 		const definitions = nonNamespaceAttributes.map((attribute) => {
 			const bind = model.binds.getOrCreateBindDefinition(attribute.nodeset);
-			return new AttributeDefinition(model.root, bind, attribute);
+			return new AttributeDefinition(model, bind, attribute);
 		});
 		return new this(definitions);
 	}

package/src/parse/model/BindDefinition.ts

@@ -38,10 +38,7 @@ export class BindDefinition<T extends BindType = BindType> extends DependencyCon
 	// https://github.com/getodk/collect/issues/3758 mentions deprecation.
 	readonly saveIncomplete: BindComputationExpression<'saveIncomplete'>;
 
-	// TODO: these are deferred until prioritized
-	// readonly preload: string | null;
-	// readonly preloadParams: string | null;
-	// readonly 'max-pixels': string | null;
+	// TODO: deferred until prioritized: readonly 'max-pixels': string | null;
 
 	protected _parentBind: BindDefinition | null | undefined;
 
@@ -95,8 +92,6 @@ export class BindDefinition<T extends BindType = BindType> extends DependencyCon
 		this.constraintMsg = MessageDefinition.from(this, 'constraintMsg');
 		this.requiredMsg = MessageDefinition.from(this, 'requiredMsg');
 
-		// this.preload = BindComputation.forExpression(this, 'preload');
-		// this.preloadParams = BindComputation.forExpression(this, 'preloadParams');
 		// this['max-pixels'] = BindComputation.forExpression(this, 'max-pixels');
 	}
 

package/src/parse/model/BindPreloadDefinition.ts

@@ -1,10 +1,18 @@
 import { JAVAROSA_NAMESPACE_URI } from '@getodk/common/constants/xmlns.ts';
 import type { PartiallyKnownString } from '@getodk/common/types/string/PartiallyKnownString.ts';
+import type { AttributeContext } from '../../instance/internal-api/AttributeContext.ts';
+import type { InstanceValueContext } from '../../instance/internal-api/InstanceValueContext.ts';
 import type { BindElement } from './BindElement.ts';
+import { XFORM_EVENT, type XFormEvent } from './Event.ts';
 
-type PartiallyKnownPreloadParameter<Known extends string> =
-	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
-	PartiallyKnownString<NonNullable<Known>> | Extract<Known, null>;
+/**
+ * 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())';
+
+type PartiallyKnownPreloadParameter<Known extends string> = PartiallyKnownString<
+	NonNullable<Known>
+>;
 
 interface PreloadParametersByType {
 	readonly uid: string | null;
@@ -61,15 +69,6 @@ const getPreloadInput = (bindElement: BindElement): AnyPreloadInput | null => {
  *
  * - {@link type}, a `jr:preload`
  * - {@link parameter}, an associated `jr:preloadParams` value
- *
- * @todo It would probably make sense for the _definition_ to also convey:
- *
- * 1. Which {@link https://getodk.github.io/xforms-spec/#events | event} the
- *    preload is semantically associated with (noting that the spec may be a tad
- *    overzealous about this association).
- *
- * 2. The constant XPath expression (or other computation?) expressed by the
- *    combined {@link type} and {@link parameter}.
  */
 export class BindPreloadDefinition<Type extends PreloadType> implements PreloadInput<Type> {
 	static from(bindElement: BindElement): AnyBindPreloadDefinition | null {
@@ -84,10 +83,43 @@ export class BindPreloadDefinition<Type extends PreloadType> implements PreloadI
 
 	readonly type: Type;
 	readonly parameter: PreloadParameter<Type>;
+	readonly event: XFormEvent;
+
+	getValue(context: AttributeContext | InstanceValueContext): string | undefined {
+		if (this.type === 'uid') {
+			return context.evaluator.evaluateString(PRELOAD_UID_EXPRESSION);
+		}
+		if (this.type === 'timestamp') {
+			return context.evaluator.evaluateString('now()');
+		}
+		if (this.type === 'date') {
+			return context.evaluator.evaluateString('today()');
+		}
+		if (this.type === 'property') {
+			const properties = context.instanceConfig.preloadProperties;
+			if (this.parameter === 'deviceid') {
+				return properties.deviceID;
+			}
+			if (this.parameter === 'email') {
+				return properties.email;
+			}
+			if (this.parameter === 'phonenumber') {
+				return properties.phoneNumber;
+			}
+			if (this.parameter === 'username') {
+				return properties.username;
+			}
+		}
+		return;
+	}
 
 	private constructor(input: PreloadInput<Type>) {
 		this.type = input.type;
 		this.parameter = input.parameter;
+		this.event =
+			this.type === 'timestamp' && this.parameter === 'end'
+				? XFORM_EVENT.xformsRevalidate
+				: XFORM_EVENT.odkInstanceFirstLoad;
 	}
 }
 

package/src/parse/model/Event.ts

@@ -0,0 +1,9 @@
+export const XFORM_EVENT = {
+	odkInstanceLoad: 'odk-instance-load',
+	odkInstanceFirstLoad: 'odk-instance-first-load',
+	odkNewRepeat: 'odk-new-repeat',
+	xformsRevalidate: 'xforms-revalidate',
+	xformsValueChanged: 'xforms-value-changed',
+} as const;
+
+export type XFormEvent = (typeof XFORM_EVENT)[keyof typeof XFORM_EVENT];

package/src/parse/model/LeafNodeDefinition.ts

@@ -6,8 +6,10 @@ import {
 } from '../../lib/names/NamespaceDeclarationMap.ts';
 import { QualifiedName } from '../../lib/names/QualifiedName.ts';
 import type { AnyBodyElementDefinition, ControlElementDefinition } from '../body/BodyDefinition.ts';
+import { AttributeDefinitionMap } from './AttributeDefinitionMap.ts';
 import type { BindDefinition } from './BindDefinition.ts';
 import { DescendentNodeDefinition } from './DescendentNodeDefinition.ts';
+import type { ModelDefinition } from './ModelDefinition.ts';
 import type { ParentNodeDefinition } from './NodeDefinition.ts';
 
 export class LeafNodeDefinition<V extends ValueType = ValueType>
@@ -20,9 +22,10 @@ export class LeafNodeDefinition<V extends ValueType = ValueType>
 	readonly namespaceDeclarations: NamespaceDeclarationMap;
 	readonly qualifiedName: QualifiedName;
 	readonly children = null;
-	readonly attributes = null;
+	readonly attributes: AttributeDefinitionMap;
 
 	constructor(
+		readonly model: ModelDefinition,
 		parent: ParentNodeDefinition,
 		bind: BindDefinition,
 		bodyElement: AnyBodyElementDefinition | null,
@@ -37,6 +40,7 @@ export class LeafNodeDefinition<V extends ValueType = ValueType>
 		this.valueType = bind.type.resolved satisfies ValueType as V;
 		this.qualifiedName = template.qualifiedName;
 		this.namespaceDeclarations = new NamespaceDeclarationMap(this);
+		this.attributes = AttributeDefinitionMap.from(model, template);
 	}
 
 	toJSON() {

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;