@getodk/xforms-engine 0.4.0 → 0.5.0

package/src/lib/reactivity/createSelectItems.ts

@@ -1,17 +1,15 @@
 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 { TextRange as ClientTextRange } from '../../client/TextRange.ts';
-import type { SelectItem } from '../../index.ts';
+import type { ActiveLanguage, SelectItem } from '../../index.ts';
+import type { EvaluationContext } from '../../instance/internal-api/EvaluationContext.ts';
+import type { TranslationContext } from '../../instance/internal-api/TranslationContext.ts';
 import type { SelectField } from '../../instance/SelectField.ts';
-import type {
-	EvaluationContext,
-	EvaluationContextRoot,
-} from '../../instance/internal-api/EvaluationContext.ts';
-import type { SubscribableDependency } from '../../instance/internal-api/SubscribableDependency.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/select/ItemDefinition.ts';
 import type { ItemsetDefinition } from '../../parse/body/control/select/ItemsetDefinition.ts';
 import { createComputedExpression } from './createComputedExpression.ts';
@@ -20,8 +18,8 @@ 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);
+const derivedItemLabel = (context: TranslationContext, value: string): DerivedItemLabel => {
+	const chunk = new TextChunk(context, 'literal', value);
 
 	return new TextRange('form-derived', 'item-label', [chunk]);
 };
@@ -61,23 +59,21 @@ const createTranslatedStaticSelectItems = (
 };
 
 class ItemsetItemEvaluationContext implements EvaluationContext {
+	readonly isAttached: Accessor<boolean>;
 	readonly scope: ReactiveScope;
-	readonly evaluator: XFormsXPathEvaluator;
-	readonly root: EvaluationContextRoot;
+	readonly evaluator: EngineXPathEvaluator;
 	readonly contextReference: Accessor<string>;
+	readonly getActiveLanguage: Accessor<ActiveLanguage>;
 
 	constructor(
-		private readonly selectField: SelectField,
-		readonly contextNode: Node
+		selectField: SelectField,
+		readonly contextNode: EngineXPathNode
 	) {
+		this.isAttached = selectField.isAttached;
 		this.scope = selectField.scope;
 		this.evaluator = selectField.evaluator;
-		this.root = selectField.root;
 		this.contextReference = selectField.contextReference;
-	}
-
-	getSubscribableDependenciesByReference(reference: string): readonly SubscribableDependency[] {
-		return this.selectField.getSubscribableDependenciesByReference(reference);
+		this.getActiveLanguage = selectField.getActiveLanguage;
 	}
 }
 
@@ -107,14 +103,18 @@ const createItemsetItems = (
 	itemset: ItemsetDefinition
 ): Accessor<readonly ItemsetItem[]> => {
 	return selectField.scope.runTask(() => {
-		const itemNodes = createComputedExpression(selectField, itemset.nodes);
-		const itemsCache = new UpsertableMap<Node, ItemsetItem>();
+		const itemNodes = createComputedExpression(selectField, itemset.nodes, {
+			defaultValue: [],
+		});
+		const itemsCache = new UpsertableMap<EngineXPathNode, ItemsetItem>();
 
 		return createMemo(() => {
 			return itemNodes().map((itemNode) => {
 				return itemsCache.upsert(itemNode, () => {
 					const context = new ItemsetItemEvaluationContext(selectField, itemNode);
-					const value = createComputedExpression(context, itemset.value);
+					const value = createComputedExpression(context, itemset.value, {
+						defaultValue: '',
+					});
 					const label = createSelectItemsetItemLabel(context, itemset, value);
 
 					return {

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(() => {

package/src/lib/xml-serialization.ts

@@ -0,0 +1,96 @@
+declare const ESCAPED_XML_TEXT_BRAND: unique symbol;
+
+export type EscapedXMLText = string & { readonly [ESCAPED_XML_TEXT_BRAND]: true };
+
+const ATTR_REGEX = /[&<>"]/;
+const CONTENT_REGEX = /[&<>]/;
+
+/**
+ * This is based on the `escapeHTML` implementation in
+ * {@link https://github.com/ryansolid/dom-expressions} (Solid's JSX transform).
+ *
+ * @see {@link https://github.com/ryansolid/dom-expressions/pull/27} for
+ * motivation to derive this implementation approach.
+ *
+ * The intent is that this can be updated easily if the base implementation
+ * changes. As such, some aspects of this implementation differ from some of our
+ * typical code style preferences.
+ *
+ * Notable changes from the base implementation:
+ *
+ * - Formatting: automated only.
+ * - Naming: the {@link text} parameter is named `html` in the base
+ *   implementation. That would be confusing if preserved.
+ * - Types:
+ *     - Parameter types are added (of course)
+ *     - Return type is branded as {@link EscapedXMLText}, to allow downstream
+ *       checks that escaping has been performed. Return statements are cast
+ *       accordingly.
+ *     - {@link text} attempts to minimize risk of double-escaping by excluding
+ *       that same branded type.
+ * - The '>' character is also escaped, necessary for producing valid XML.
+ *
+ * As with the base implementation, we leave some characters unescaped:
+ *
+ * - " (double quote): except when {@link attr} is `true`.
+ *
+ * - ' (single quote): on the assumption that attributes are always serialized
+ *   in double quotes. If we ever move this to `@getodk/common`, we'd want to
+ *   reconsider this assumption.
+ */
+export const escapeXMLText = <Text extends string>(
+	text: Exclude<Text, EscapedXMLText>,
+	attr?: boolean
+): EscapedXMLText => {
+	const match = (attr ? ATTR_REGEX : CONTENT_REGEX).exec(text);
+	if (!match) return text as string as EscapedXMLText;
+	let index = 0;
+	let lastIndex = 0;
+	let out = '';
+	let escape = '';
+	for (index = match.index; index < text.length; index++) {
+		switch (text.charCodeAt(index)) {
+			case 34: // "
+				if (!attr) continue;
+				escape = '&quot;';
+				break;
+			case 38: // &
+				escape = '&amp;';
+				break;
+			case 60: // <
+				escape = '&lt;';
+				break;
+			case 62: // >
+				escape = '&gt;';
+				break;
+			default:
+				continue;
+		}
+		if (lastIndex !== index) out += text.substring(lastIndex, index);
+		lastIndex = index + 1;
+		out += escape;
+	}
+	return lastIndex !== index
+		? ((out + text.substring(lastIndex, index)) as EscapedXMLText)
+		: (out as EscapedXMLText);
+};
+
+const serializeElementXML = (nodeName: string, children: string): string => {
+	if (children === '') {
+		return `<${nodeName}/>`;
+	}
+
+	// TODO: attributes
+	return `<${nodeName}>${children}</${nodeName}>`;
+};
+
+export const serializeParentElementXML = (
+	nodeName: string,
+	serializedChildren: readonly string[]
+): string => {
+	return serializeElementXML(nodeName, serializedChildren.join(''));
+};
+
+export const serializeLeafElementXML = (nodeName: string, xmlValue: EscapedXMLText): string => {
+	return serializeElementXML(nodeName, xmlValue.normalize());
+};