@getodk/xforms-engine 0.4.0 → 0.6.0

package/src/lib/reactivity/createItemCollection.ts

@@ -0,0 +1,173 @@
+import { UpsertableMap } from '@getodk/common/lib/collections/UpsertableMap.ts';
+import type { Accessor } from 'solid-js';
+import { createMemo } from 'solid-js';
+import type { ActiveLanguage } from '../../client/FormLanguage.ts';
+import type { SelectItem } from '../../client/SelectNode.ts';
+import type { RankItem } from '../../client/RankNode.ts';
+import type { TextRange as ClientTextRange } from '../../client/TextRange.ts';
+import type { EvaluationContext } from '../../instance/internal-api/EvaluationContext.ts';
+import type { TranslationContext } from '../../instance/internal-api/TranslationContext.ts';
+import type { SelectControl } from '../../instance/SelectControl.ts';
+import type { RankControl } from '../../instance/RankControl.ts';
+import { TextChunk } from '../../instance/text/TextChunk.ts';
+import { TextRange } from '../../instance/text/TextRange.ts';
+import type { EngineXPathNode } from '../../integration/xpath/adapter/kind.ts';
+import type { EngineXPathEvaluator } from '../../integration/xpath/EngineXPathEvaluator.ts';
+import type { ItemDefinition } from '../../parse/body/control/ItemDefinition.ts';
+import type { ItemsetDefinition } from '../../parse/body/control/ItemsetDefinition.ts';
+import { createComputedExpression } from './createComputedExpression.ts';
+import type { ReactiveScope } from './scope.ts';
+import { createTextRange } from './text/createTextRange.ts';
+
+export type ItemCollectionControl = RankControl | SelectControl;
+type Item = RankItem | SelectItem;
+type DerivedItemLabel = ClientTextRange<'item-label', 'form-derived'>;
+
+const derivedItemLabel = (context: TranslationContext, value: string): DerivedItemLabel => {
+	const chunk = new TextChunk(context, 'literal', value);
+
+	return new TextRange('form-derived', 'item-label', [chunk]);
+};
+
+const createItemLabel = (
+	context: EvaluationContext,
+	definition: ItemDefinition
+): Accessor<ClientTextRange<'item-label'>> => {
+	const { label, value } = definition;
+
+	if (label == null) {
+		return () => derivedItemLabel(context, value);
+	}
+
+	return createTextRange(context, 'item-label', label);
+};
+
+const createTranslatedStaticItems = (
+	control: ItemCollectionControl,
+	items: readonly ItemDefinition[]
+): Accessor<readonly Item[]> => {
+	return control.scope.runTask(() => {
+		const labeledItems = items.map((item) => {
+			const { value } = item;
+			const label = createItemLabel(control, item);
+
+			return () => ({
+				value,
+				label: label(),
+			});
+		});
+
+		return createMemo(() => {
+			return labeledItems.map((item) => item());
+		});
+	});
+};
+
+class ItemsetItemEvaluationContext implements EvaluationContext {
+	readonly isAttached: Accessor<boolean>;
+	readonly scope: ReactiveScope;
+	readonly evaluator: EngineXPathEvaluator;
+	readonly contextReference: Accessor<string>;
+	readonly getActiveLanguage: Accessor<ActiveLanguage>;
+
+	constructor(
+		control: ItemCollectionControl,
+		readonly contextNode: EngineXPathNode
+	) {
+		this.isAttached = control.isAttached;
+		this.scope = control.scope;
+		this.evaluator = control.evaluator;
+		this.contextReference = control.contextReference;
+		this.getActiveLanguage = control.getActiveLanguage;
+	}
+}
+
+const createItemsetItemLabel = (
+	context: EvaluationContext,
+	definition: ItemsetDefinition,
+	itemValue: Accessor<string>
+): Accessor<ClientTextRange<'item-label'>> => {
+	const { label } = definition;
+
+	if (label == null) {
+		return createMemo(() => {
+			return derivedItemLabel(context, itemValue());
+		});
+	}
+
+	return createTextRange(context, 'item-label', label);
+};
+
+interface ItemsetItem {
+	label(): ClientTextRange<'item-label'>;
+	value(): string;
+}
+
+const createItemsetItems = (
+	control: ItemCollectionControl,
+	itemset: ItemsetDefinition
+): Accessor<readonly ItemsetItem[]> => {
+	return control.scope.runTask(() => {
+		const itemNodes = createComputedExpression(control, itemset.nodes, {
+			defaultValue: [],
+		});
+		const itemsCache = new UpsertableMap<EngineXPathNode, ItemsetItem>();
+
+		return createMemo(() => {
+			return itemNodes().map((itemNode) => {
+				return itemsCache.upsert(itemNode, () => {
+					const context = new ItemsetItemEvaluationContext(control, itemNode);
+					const value = createComputedExpression(context, itemset.value, {
+						defaultValue: '',
+					});
+					const label = createItemsetItemLabel(context, itemset, value);
+
+					return {
+						label,
+						value,
+					};
+				});
+			});
+		});
+	});
+};
+
+const createItemset = (
+	control: ItemCollectionControl,
+	itemset: ItemsetDefinition
+): Accessor<readonly Item[]> => {
+	return control.scope.runTask(() => {
+		const itemsetItems = createItemsetItems(control, itemset);
+
+		return createMemo(() => {
+			return itemsetItems().map((item) => {
+				return {
+					label: item.label(),
+					value: item.value(),
+				};
+			});
+		});
+	});
+};
+
+/**
+ * Creates a reactive computation of a {@link ItemCollectionControl}'s
+ * {@link Item}s, in support of the field's `valueOptions`.
+ *
+ * - The control defined with static `<item>`s will compute to an corresponding
+ *   static list of items.
+ * - The control defined with a computed `<itemset>` will compute to a reactive list
+ *   of items.
+ * - Items of both will produce {@link ItemType.label | labels} reactive to
+ *   their appropriate dependencies (whether relative to the itemset item node,
+ *   referencing a form's `itext` translations, etc).
+ */
+export const createItemCollection = (control: ItemCollectionControl): Accessor<readonly Item[]> => {
+	const { items, itemset } = control.definition.bodyElement;
+
+	if (itemset != null) {
+		return createItemset(control, itemset);
+	}
+
+	return createTranslatedStaticItems(control, items);
+};

package/src/lib/reactivity/createNoteReadonlyThunk.ts

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

package/src/lib/reactivity/createTranslationState.ts

@@ -0,0 +1,61 @@
+import type { XFormsXPathEvaluator } from '@getodk/xpath';
+import type { Accessor } from 'solid-js';
+import { createComputed, createSignal } from 'solid-js';
+import type { ActiveLanguage, FormLanguage, FormLanguages } from '../../client/FormLanguage.ts';
+import type { EngineXPathEvaluator } from '../../integration/xpath/EngineXPathEvaluator.ts';
+import type { ReactiveScope } from './scope.ts';
+import type { SimpleAtomicStateSetter } from './types.ts';
+
+interface TranslationState {
+	readonly languages: FormLanguages;
+	readonly getActiveLanguage: Accessor<ActiveLanguage>;
+	readonly setActiveLanguage: SimpleAtomicStateSetter<FormLanguage>;
+}
+
+/**
+ * @todo It's been very silly all along that {@link XFormsXPathEvaluator} is
+ * responsible for parsing translation languages, and maintaining the active
+ * language state. It is especially silly now that we've moved _part of the
+ * parsing_ up to the constructor call site. Let's finish off that awkwardness
+ * in a subsequent refactor.
+ */
+export const createTranslationState = (
+	scope: ReactiveScope,
+	evaluator: EngineXPathEvaluator
+): TranslationState => {
+	const activeLanguageName = evaluator.getActiveLanguage();
+	const languageNames = evaluator.getLanguages();
+
+	let defaultLanguage: ActiveLanguage;
+	let languages: FormLanguages;
+
+	if (activeLanguageName == null) {
+		defaultLanguage = { isSyntheticDefault: true, language: '' };
+		languages = [defaultLanguage];
+	} else {
+		const inactiveLanguages = languageNames
+			.filter((languageName) => languageName !== activeLanguageName)
+			.map((language) => ({ language }));
+
+		defaultLanguage = { language: activeLanguageName };
+		languages = [defaultLanguage, ...inactiveLanguages];
+	}
+
+	const [getActiveLanguage, baseSetActiveLanguage] = createSignal(defaultLanguage);
+
+	const setActiveLanguage: SimpleAtomicStateSetter<FormLanguage> = (value) => {
+		return baseSetActiveLanguage(value);
+	};
+
+	scope.runTask(() => {
+		createComputed(() => {
+			evaluator.setActiveLanguage(getActiveLanguage().language);
+		});
+	});
+
+	return {
+		languages,
+		getActiveLanguage,
+		setActiveLanguage,
+	};
+};

package/src/lib/reactivity/createValueState.ts

@@ -1,8 +1,7 @@
-import { createComputed, createMemo, createSignal, untrack } from 'solid-js';
-import type { SubscribableDependency } from '../../instance/internal-api/SubscribableDependency.ts';
+import { createComputed, createMemo, createSignal, untrack, type Signal } from 'solid-js';
+import { ErrorProductionDesignPendingError } from '../../error/ErrorProductionDesignPendingError.ts';
 import type { ValueContext } from '../../instance/internal-api/ValueContext.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';
 
@@ -19,8 +18,7 @@ export interface ValueStateOptions {
 	 *   other words, this value should not be used for edits.
 	 *
 	 * - 'PRIMARY_INSTANCE': Derives the initial state from the current text
-	 *   content of the {@link ValueNode.contextNode} (currently an XML DOM
-	 *   backing store/source of thruth for primary instance state). This option
+	 *   content of the {@link ValueNode.contextNode}. This option
 	 *   should be specified when initializing a form with existing primary
 	 *   instance data, such as when editing a previous submission.
 	 *
@@ -33,110 +31,54 @@ export interface ValueStateOptions {
 	readonly initialValueSource?: InitialValueSource;
 }
 
-interface PersistedValueState {
-	readonly isRelevant: boolean;
-	readonly value: string;
-}
-
-type PrimaryInstanceValueState = SimpleAtomicState<string>;
-
-type ValueState<RuntimeValue> = SimpleAtomicState<RuntimeValue>;
-
-/**
- * Creates a signal which:
- *
- * 1. Persists its state to the primary instance's
- *    {@link ValueContext.contextNode | contextNode} on state changes.
- * 2. Propagates downstream reactivity only after that write is persisted.
- *
- * This ensures that reactive subscriptions get a consistent view of a node's
- * current state, regardless of whether they derive state from values in the
- * primary instance (currently: computed {@link DependentExpression}
- * evaluations) or from other aspects of reactive runtime state (generally,
- * everything besides computed {@link DependentExpression}s).
- */
-const createPrimaryInstanceValueState = <RuntimeValue>(
+const getInitialValue = <RuntimeValue>(
 	context: ValueContext<RuntimeValue>,
 	options: ValueStateOptions
-): PrimaryInstanceValueState => {
-	const { contextNode, definition, scope } = context;
-	const { initialValueSource } = options;
-	const { defaultValue } = definition;
+): string => {
+	const { initialValueSource = 'FORM_DEFAULT' } = options;
 
-	return scope.runTask(() => {
-		// prettier-ignore
-		const initialValue =
-			initialValueSource === 'PRIMARY_INSTANCE'
-				? contextNode.textContent ?? defaultValue
-				: defaultValue;
+	if (initialValueSource === 'FORM_DEFAULT') {
+		return context.definition.defaultValue;
+	}
 
-		const persistedValueState = createSignal<PersistedValueState>(
-			{
-				isRelevant: context.isRelevant(),
-				value: initialValue,
-			},
-			{
-				// This could return a single boolean expression, but checking each
-				// equality condition separately feels like it more clearly expresses
-				// the intent.
-				equals: (previous, updated) => {
-					if (updated.isRelevant !== previous.isRelevant) {
-						return false;
-					}
+	throw new ErrorProductionDesignPendingError('Edit implementation pending');
+};
 
-					return updated.value === previous.value;
-				},
-			}
-		);
-		const [persistedValue, setValueForPersistence] = persistedValueState;
+type BaseValueState = Signal<string>;
 
-		createComputed(() => {
-			const isRelevant = context.isRelevant();
+type RelevantValueState = SimpleAtomicState<string>;
 
-			setValueForPersistence((persisted) => {
-				return {
-					isRelevant,
-					value: persisted.value,
-				};
-			});
-		});
+/**
+ * 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 = <RuntimeValue>(
+	context: ValueContext<RuntimeValue>,
+	baseValueState: BaseValueState
+): RelevantValueState => {
+	return context.scope.runTask(() => {
+		const [getRelevantValue, setValue] = baseValueState;
 
-		const toSignalValue = (current: PersistedValueState): string => {
-			if (current.isRelevant) {
-				return current.value;
+		const getValue = createMemo(() => {
+			if (context.isRelevant()) {
+				return getRelevantValue();
 			}
 
 			return '';
-		};
-
-		const [signalValue, setSignalValue] = createSignal(toSignalValue(persistedValue()));
-
-		createComputed(() => {
-			const { isRelevant, value } = persistedValue();
-			const preparedTextContent = isRelevant ? value : '';
-			const assignedTextContent = (contextNode.textContent = preparedTextContent);
-
-			setSignalValue(assignedTextContent);
 		});
 
-		const setPrimaryInstanceValue: SimpleAtomicStateSetter<string> = (value) => {
-			// TODO: Check (error?) for non-relevant value change?
-			const persisted = setValueForPersistence({
-				isRelevant: context.isRelevant(),
-				value,
-			});
-
-			return persisted.value;
-		};
-
-		return [signalValue, setPrimaryInstanceValue];
+		return [getValue, setValue];
 	});
 };
 
+type RuntimeValueState<RuntimeValue> = SimpleAtomicState<RuntimeValue>;
+
 /**
- * Wraps a node's {@link PrimaryInstanceValueState} in a signal-like interface
- * which automatically encodes and decodes a node's runtime value
- * representation:
+ * Wraps {@link relevantValueState} in a signal-like interface which
+ * automatically encodes and decodes a node's runtime value representation:
  *
  * - Values read by a node will be read from the current state as persisted in
  *   the primary instance, then {@link ValueContext.decodeValue | decoded} (as
@@ -144,21 +86,17 @@ const createPrimaryInstanceValueState = <RuntimeValue>(
  *   functionality provided by that node.
  *
  * - Values written by a node will be {@link ValueContext.encodeValue | encoded}
- *   (also as implemented by that node) into a string appropriate to persist to
- *   the primary instance, and written to it as such.
- *
- * - Downstream reactive computations should subscribe to updates to this
- *   runtime state (suggesting the value node itself should access this state in
- *   its {@link SubscribableDependency.subscribe} implementation).
+ *   (also as implemented by that node) into a string value appropriate for
+ *   serialization in an instance submission.
  */
 const createRuntimeValueState = <RuntimeValue>(
 	context: ValueContext<RuntimeValue>,
-	primaryInstanceState: PrimaryInstanceValueState
-): ValueState<RuntimeValue> => {
+	relevantValueState: RelevantValueState
+): RuntimeValueState<RuntimeValue> => {
 	const { decodeValue, encodeValue } = context;
 
 	return context.scope.runTask(() => {
-		const [primaryInstanceValue, setPrimaryInstanceValue] = primaryInstanceState;
+		const [primaryInstanceValue, setPrimaryInstanceValue] = relevantValueState;
 		const getRuntimeValue = createMemo(() => {
 			return decodeValue(primaryInstanceValue());
 		});
@@ -212,10 +150,12 @@ const createCalculation = <RuntimeValue>(
 	calculateDefinition: BindComputationExpression<'calculate'>
 ): void => {
 	context.scope.runTask(() => {
-		const calculate = createComputedExpression(context, calculateDefinition);
+		const calculate = createComputedExpression(context, calculateDefinition, {
+			defaultValue: '',
+		});
 
 		createComputed(() => {
-			if (context.isRelevant()) {
+			if (context.isAttached() && context.isRelevant()) {
 				const calculated = calculate();
 				const value = context.decodeValue(calculated);
 
@@ -225,34 +165,36 @@ const createCalculation = <RuntimeValue>(
 	});
 };
 
+type ValueState<RuntimeValue> = SimpleAtomicState<RuntimeValue>;
+
 /**
  * Provides a consistent interface for value nodes of any type which:
  *
- * - derives initial state from either the existing primary instance state (e.g.
- *   for edits) or the node's definition (e.g. initializing a new submission)
- * - decodes primary instance state into the value node's runtime type
- * - encodes and persists updated values to the primary instance
+ * - derives initial state from either an existing instance (e.g. for edits) or
+ *   the node's definition (e.g. initializing a new submission)
+ * - 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
- * - ensures any downstream reactive dependencies are updated only after writes
- *   (whether performed by a client, or by a reactive `calculate` computation)
- *   are persisted, ensuring a consistent view of state when downstream
- *   computations perform XPath evaluations against that primary instance state
+ * - prevents downstream writes to nodes in a readonly state
  */
 export const createValueState = <RuntimeValue>(
 	context: ValueContext<RuntimeValue>,
 	options: ValueStateOptions = {}
 ): ValueState<RuntimeValue> => {
-	const primaryInstanceState = createPrimaryInstanceValueState(context, options);
-	const runtimeState = createRuntimeValueState(context, primaryInstanceState);
-
-	const { calculate } = context.definition.bind;
+	return context.scope.runTask(() => {
+		const initialValue = getInitialValue(context, options);
+		const baseValueState = createSignal(initialValue);
+		const valueState = createRelevantValueState(context, baseValueState);
+		const runtimeState = createRuntimeValueState(context, valueState);
+		const { calculate } = context.definition.bind;
 
-	if (calculate != null) {
-		const [, setValue] = runtimeState;
+		if (calculate != null) {
+			const [, setValue] = runtimeState;
 
-		createCalculation(context, setValue, calculate);
-	}
+			createCalculation(context, setValue, calculate);
+		}
 
-	return guardDownstreamReadonlyWrites(context, runtimeState);
+		return guardDownstreamReadonlyWrites(context, runtimeState);
+	});
 };

package/src/lib/reactivity/materializeCurrentStateChildren.ts

@@ -1,13 +1,13 @@
+import type { FormNodeID } from '../../client/identity.ts';
 import type { AnyChildNode } from '../../instance/hierarchy.ts';
-import type { NodeID } from '../../instance/identity.ts';
 import type { ChildrenState, createChildrenState } from './createChildrenState.ts';
 import type { ClientState } from './node-state/createClientState.ts';
 import type { CurrentState } from './node-state/createCurrentState.ts';
 import type { ReactiveScope } from './scope.ts';
 
 interface InconsistentChildrenStateDetails {
-	readonly missingIds: readonly NodeID[];
-	readonly unexpectedIds: readonly NodeID[];
+	readonly missingIds: readonly FormNodeID[];
+	readonly unexpectedIds: readonly FormNodeID[];
 }
 
 class InconsistentChildrenStateError extends Error {
@@ -37,7 +37,7 @@ class InconsistentChildrenStateError extends Error {
 }
 
 export interface EncodedParentState {
-	readonly children: readonly NodeID[];
+	readonly children: readonly FormNodeID[];
 }
 
 /**
@@ -58,7 +58,7 @@ export interface EncodedParentState {
  * @todo should we throw rather than warn until we have this confidence?
  */
 const reportInconsistentChildrenState = (
-	expectedClientIds: readonly NodeID[],
+	expectedClientIds: readonly FormNodeID[],
 	actualNodes: readonly AnyChildNode[]
 ): void => {
 	const actualIds = actualNodes.map((node) => node.nodeId);
@@ -88,8 +88,8 @@ export type MaterializedChildren<
 /**
  * Creates a wrapper proxy around a parent node's {@link CurrentState} to map
  * `children` state, which is written to the node's (internal, synchronized)
- * {@link ClientState} as an array of {@link NodeID}s, back to the node objects
- * corresponding to those IDs.
+ * {@link ClientState} as an array of {@link FormNodeID}s, back to the node
+ * objects corresponding to those IDs.
  *
  * @see {@link createChildrenState} for further detail.
  */

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

@@ -29,7 +29,9 @@ const createComputedTextChunk = (
 	}
 
 	return context.scope.runTask(() => {
-		const getText = createComputedExpression(context, textSource);
+		const getText = createComputedExpression(context, textSource, {
+			defaultValue: '',
+		});
 
 		return {
 			source,
@@ -43,14 +45,13 @@ const createTextChunks = (
 	textSources: readonly AnyTextChunkExpression[]
 ): Accessor<readonly TextChunk[]> => {
 	return context.scope.runTask(() => {
-		const { root } = context;
 		const chunkComputations = textSources.map((textSource) => {
 			return createComputedTextChunk(context, textSource);
 		});
 
 		return createMemo(() => {
 			return chunkComputations.map(({ source, getText }) => {
-				return new TextChunk(root, source, getText());
+				return new TextChunk(context, source, getText());
 			});
 		});
 	});

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

@@ -32,8 +32,8 @@ const collectViolationReferences = (
 	return context.getChildren().flatMap((child) => {
 		switch (child.nodeType) {
 			case 'model-value':
+			case 'input':
 			case 'note':
-			case 'string':
 			case 'select':
 			case 'range':
 			case 'rank':

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

@@ -33,7 +33,7 @@ const engineViolationMessage = <Role extends ValidationTextRole>(
 	role: Role
 ): Accessor<EngineViolationMessage<Role>> => {
 	const messageText = VALIDATION_TEXT[role];
-	const chunk = new TextChunk(context.root, 'literal', messageText);
+	const chunk = new TextChunk(context, 'literal', messageText);
 	const message = new TextRange('engine', role, [chunk]);
 
 	return () => message;
@@ -75,9 +75,8 @@ const createConstraintValidation = (
 		}
 
 		const isValid = createComputedExpression(context, constraint, {
-			arbitraryDependencies: [context],
+			defaultValue: true,
 		});
-
 		const message = createViolationMessage(context, 'constraintMsg', constraintMsg);
 
 		return createMemo(() => {