@getodk/xforms-engine 0.4.0 → 0.6.0

package/src/lib/names/QualifiedName.ts

@@ -0,0 +1,170 @@
+import type { XPathDOMAdapter } from '@getodk/xpath';
+import { NamespaceURL } from './NamespaceURL.ts';
+
+export type NamespaceURI = NamespaceURL | null;
+export type QualifiedNamePrefix = string | null;
+
+export interface NamespaceQualifiedNameSource {
+	readonly namespaceURI: NamespaceURI | string;
+	readonly localName: string;
+
+	/**
+	 * Note that this property is intentionally optional as one of the
+	 * {@link QualifiedNameSource | QualifiedName source input}, and its absence
+	 * is treated differently from an explicitly assigned `null` value.
+	 *
+	 * @see {@link SourcePrefixUnspecified}, {@link DeferredPrefix}
+	 */
+	readonly prefix?: QualifiedNamePrefix;
+}
+
+const SOURCE_PREFIX_UNSPECIFIED = Symbol('SOURCE_PREFIX_UNSPECIFIED');
+
+/**
+ * May be used as a placeholder for a {@link QualifiedName.prefix}, where the
+ * actual prefix may not be known at definition time.
+ *
+ * Example: parsing non-XML sources into an XML-like tree, e.g. for XPath
+ * evaluation; in which case, we may not need to resolve a prefix for the name
+ * until such a node is serialized as XML, if it ever is.
+ */
+type SourcePrefixUnspecified = typeof SOURCE_PREFIX_UNSPECIFIED;
+
+/**
+ * Represents a {@link QualifiedName.prefix} whose resolution may be deferred,
+ * e.g. until all requisite parsing is complete and/or until XML serialization
+ * requires use of a prefix to represent the corresponding
+ * {@link QualifiedName.namespaceURI}.
+ */
+// prettier-ignore
+type DeferredPrefix =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| string
+	| null
+	| SourcePrefixUnspecified;
+
+interface DeferredPrefixedQualifiedNameSource {
+	readonly namespaceURI: NamespaceURI | string;
+	readonly prefix: DeferredPrefix;
+	readonly localName: string;
+}
+
+// prettier-ignore
+export type QualifiedNameSource =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| NamespaceQualifiedNameSource
+	| DeferredPrefixedQualifiedNameSource;
+
+interface PrefixResolutionOptions {
+	lookupPrefix(namespaceURI: NamespaceURI | string): string | null;
+}
+
+/**
+ * @todo This is in the `lib` directory because it's a cross-cutting concern,
+ * applicable to:
+ *
+ * - Parsing XML into a useful runtime data model (usage which motivated initial
+ *   development of this class)
+ * - Serializing XML from a runtime data model (also motivated initial dev)
+ * - `@getodk/xpath` (internal) e.g. references to
+ *   {@link https://www.w3.org/TR/REC-xml-names/#NT-QName | QName} in various
+ *   parts of XPath expression _syntax_, as well as various parts of the package
+ *   interpreting those parts of syntax
+ * - `@getodk/xpath` (cross-package), e.g. in aspects of the
+ *   {@link XPathDOMAdapter} APIs, and implementations thereof
+ * - A zillion potential optimizations, e.g. where names are useful in a lookup
+ *   table (or used in conjunction with other information to construct keys for
+ *   same)
+ *
+ * @todo As a cross-cutting concern, there are subtle but important differences
+ * between certain XPath and XML semantics around expressions of a "null"
+ * {@link prefix}. E.g. in the expression `/foo`, **technically** the `foo` Step
+ * should select child elements _in the null namespace_, whereas in most other
+ * cases a null prefix (when explicitly assigned `null`, rather than
+ * {@link DeferredPrefix | deferred for later resolution}) is expected to
+ * correspond _to the default namespace_ (whatever that is in the context of the
+ * {@link QualifiedName | qualified-named thing}).
+ *
+ * @todo As a mechanism for many optimizations, an evolution of this class would
+ * be **BY FAR** most useful if it can be treated as a _value type_, despite
+ * challenges using non-primitives as such in a JS runtime. To be clear: it
+ * would be most useful if every instance of {@link QualifiedName} having the
+ * same property values (or in some cases, the same combined
+ * {@link namespaceURI}/{@link localName} or combined
+ * {@link prefix}/{@link localName}) would also have _reference equality_ with
+ * other instances having the same property values (or pertinent subset
+ * thereof). Making a somewhat obvious point explicit: this would be
+ * particularly useful in cases where a lookup table is implemented as a native
+ * {@link Map}, where using {@link QualifiedName} as a key would break
+ * expectations (and probably quite a lot of functionality!) if 2+ equivalent
+ * keys mapped to different values.
+ *
+ * @todo Where we would want to treat instances as a value type, it would be
+ * useful to look at prior art for representation of the same data as a string.
+ * One frame of reference worth looking at is
+ * {@link https://www.w3.org/TR/xpath-30/#prod-xpath30-URIQualifiedName | XPath 3.0's URIQualifiedName}
+ * (but note that this syntax is mutually exclusive with the prefixed `QName`).
+ */
+export class QualifiedName implements DeferredPrefixedQualifiedNameSource {
+	private readonly defaultPrefixResolutionOptions: PrefixResolutionOptions;
+
+	readonly namespaceURI: NamespaceURI;
+
+	/**
+	 * @see {@link SourcePrefixUnspecified}, {@link DeferredPrefix}
+	 */
+	readonly prefix: DeferredPrefix;
+
+	readonly localName: string;
+
+	constructor(source: QualifiedNameSource) {
+		const { localName } = source;
+
+		let prefix = source.prefix;
+
+		if (typeof prefix === 'undefined') {
+			prefix = SOURCE_PREFIX_UNSPECIFIED;
+		}
+
+		const namespaceURI = NamespaceURL.from(source.namespaceURI);
+
+		this.namespaceURI = namespaceURI;
+		this.prefix = prefix;
+		this.localName = localName;
+
+		this.defaultPrefixResolutionOptions = {
+			lookupPrefix: () => {
+				if (prefix === SOURCE_PREFIX_UNSPECIFIED) {
+					throw new Error(`Failed to resolve prefix for namespace URI: ${String(namespaceURI)}`);
+				}
+
+				return prefix;
+			},
+		};
+	}
+
+	/**
+	 * @todo at time of writing, it's not expected we will actually supply
+	 * {@link options} in calls to this method! Current calls are from definitions
+	 * whose prefixes are known at parse time (i.e. they are prefixed in the
+	 * source XML from which they're parsed).
+	 *
+	 * The intent of accepting the options here now is to leave a fairly large
+	 * breadcrumb, for any use case where we might want to serialize XML from
+	 * artificially constructed DOM-like trees (e.g. `StaticNode` implementations
+	 * defined by parsing non-XML external secondary instances such as CSV and
+	 * GeoJSON). AFAIK this doesn't correspond to any known feature in the "like
+	 * Collect" scope, but it could have implications for inspecting form details
+	 * in e.g. "debug/form design/dev mode" scenarios.
+	 */
+	getPrefixedName(options: PrefixResolutionOptions = this.defaultPrefixResolutionOptions): string {
+		const { namespaceURI, localName } = this;
+		const prefix = options.lookupPrefix(namespaceURI);
+
+		if (prefix == null) {
+			return localName;
+		}
+
+		return `${prefix}:${localName}`;
+	}
+}

package/src/lib/number-parsers.ts

@@ -0,0 +1,25 @@
+export const parseToInteger = (value: string | null): number | null => {
+	if (value === null) {
+		return null;
+	}
+
+	const parsed = Number(value);
+	if (typeof value !== 'string' || value.trim() === '' || !Number.isInteger(parsed)) {
+		throw new Error(`Expected an integer, but got: ${value}`);
+	}
+
+	return parsed;
+};
+
+export const parseToFloat = (value: string | null): number | null => {
+	if (value === null) {
+		return null;
+	}
+
+	const parsed = Number(value);
+	if (typeof value !== 'string' || value.trim() === '' || Number.isNaN(parsed)) {
+		throw new Error(`Expected a float, but got: ${value}`);
+	}
+
+	return parsed;
+};

package/src/lib/reactivity/createChildrenState.ts

@@ -1,8 +1,8 @@
 import type { Accessor, Setter, Signal } from 'solid-js';
 import { createSignal } from 'solid-js';
+import type { FormNodeID } from '../../client/identity.ts';
 import type { OpaqueReactiveObjectFactory } from '../../index.ts';
 import type { AnyChildNode, AnyParentNode } from '../../instance/hierarchy.ts';
-import type { NodeID } from '../../instance/identity.ts';
 import type { materializeCurrentStateChildren } from './materializeCurrentStateChildren.ts';
 import type { ClientState } from './node-state/createClientState.ts';
 import type { CurrentState } from './node-state/createCurrentState.ts';
@@ -12,14 +12,15 @@ export interface ChildrenState<Child extends AnyChildNode> {
 	readonly children: Signal<readonly Child[]>;
 	readonly getChildren: Accessor<readonly Child[]>;
 	readonly setChildren: Setter<readonly Child[]>;
-	readonly childIds: Accessor<readonly NodeID[]>;
+	readonly childIds: Accessor<readonly FormNodeID[]>;
 }
 
 /**
  * Creates a synchronized pair of:
  *
  * - Internal children state suitable for all parent node types
- * - The same children state computed as an array of each child's {@link NodeID}
+ * - The same children state computed as an array of each child's
+ *   {@link FormNodeID}
  *
  * This state is used, in tandem with {@link materializeCurrentStateChildren},
  * to ensure children in **client-facing** state are not written into nested
@@ -34,11 +35,12 @@ export interface ChildrenState<Child extends AnyChildNode> {
  * The produced {@link ChildrenState.childIds} memo is intended to be used to
  * specify each parent node's `children` in an instance of {@link EngineState}.
  * In so doing, the node's corresponding (internal, synchronized)
- * {@link ClientState} will likewise store only the children's {@link NodeID}s.
+ * {@link ClientState} will likewise store only the children's
+ * {@link FormNodeID}s.
  *
  * As a client reacts to changes in a given parent node's `children` state, that
  * node's {@link CurrentState} should produce the child nodes corresponding to
- * those {@link NodeID}s with the aforementioned
+ * those {@link FormNodeID}s with the aforementioned
  * {@link materializeCurrentStateChildren}.
  */
 export const createChildrenState = <Parent extends AnyParentNode, Child extends AnyChildNode>(
@@ -65,7 +67,7 @@ export const createChildrenState = <Parent extends AnyParentNode, Child extends
 		 * likely also slightly more efficient. We can revisit the tradeoff if/when
 		 * those hypothetical generalizations become a priority.
 		 */
-		const ids = createSignal<readonly NodeID[]>([]);
+		const ids = createSignal<readonly FormNodeID[]>([]);
 		const [childIds, setChildIds] = ids;
 
 		type ChildrenSetterCallback = (prev: readonly Child[]) => readonly Child[];

package/src/lib/reactivity/createComputedExpression.ts

@@ -1,9 +1,9 @@
 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 { EngineXPathNode } from '../../integration/xpath/adapter/kind.ts';
+import type { EngineXPathEvaluator } from '../../integration/xpath/EngineXPathEvaluator.ts';
 import type {
 	DependentExpression,
 	DependentExpressionResultType,
@@ -12,7 +12,7 @@ import { isConstantExpression } from '../../parse/xpath/semantic-analysis.ts';
 
 interface ComputedExpressionResults {
 	readonly boolean: boolean;
-	readonly nodes: Node[];
+	readonly nodes: EngineXPathNode[];
 	readonly number: number;
 	readonly string: string;
 }
@@ -25,16 +25,18 @@ type EvaluatedExpression<
 // prettier-ignore
 type ExpressionEvaluator<
 	Type extends DependentExpressionResultType
-> = () => EvaluatedExpression<Type>
+> = () => EvaluatedExpression<Type>;
+
+interface ExpressionEvaluatorOptions {
+	get contextNode(): EngineXPathNode;
+}
 
 const expressionEvaluator = <Type extends DependentExpressionResultType>(
-	evaluator: XFormsXPathEvaluator,
-	contextNode: Node,
+	evaluator: EngineXPathEvaluator,
 	type: Type,
-	expression: string
+	expression: string,
+	options: ExpressionEvaluatorOptions
 ): ExpressionEvaluator<Type> => {
-	const options = { contextNode };
-
 	switch (type) {
 		case 'boolean':
 			return (() => {
@@ -61,50 +63,71 @@ const expressionEvaluator = <Type extends DependentExpressionResultType>(
 	}
 };
 
+type DefaultEvaluationsByType = {
+	readonly [Type in DependentExpressionResultType]: EvaluatedExpression<Type>;
+};
+
+const DEFAULT_BOOLEAN_EVALUATION = false;
+const DEFAULT_NODES_EVALUATION: [] = [];
+const DEFAULT_NUMBER_EVALUATION = NaN;
+const DEFAULT_STRING_EVALUATION = '';
+
+const defaultEvaluationsByType: DefaultEvaluationsByType = {
+	boolean: DEFAULT_BOOLEAN_EVALUATION,
+	nodes: DEFAULT_NODES_EVALUATION,
+	number: DEFAULT_NUMBER_EVALUATION,
+	string: DEFAULT_STRING_EVALUATION,
+};
+
 // prettier-ignore
 type ComputedExpression<Type extends DependentExpressionResultType> = Accessor<
 	EvaluatedExpression<Type>
 >;
 
-interface CreateComputedExpressionOptions {
-	readonly arbitraryDependencies?: readonly SubscribableDependency[];
+interface CreateComputedExpressionOptions<Type extends DependentExpressionResultType> {
+	/**
+	 * If a default value is provided, {@link createComputedExpression} will
+	 * produce this value for computations in a non-attached evaluation context,
+	 * i.e. when evaluating an expression against a node which has not yet been
+	 * appended to its parents children state (or which has since been removed
+	 * from that state). A non-attached state is detected when
+	 * {@link EvaluationContext.isAttached} returns false.
+	 *
+	 * If no default value is provided, an implicit default value is produced as
+	 * appropriate for the expression's intrinsic result type.
+	 *
+	 * @see {@link defaultEvaluationsByType} for these implicit defaults.
+	 */
+	readonly defaultValue?: EvaluatedExpression<Type>;
 }
 
 export const createComputedExpression = <Type extends DependentExpressionResultType>(
 	context: EvaluationContext,
 	dependentExpression: DependentExpression<Type>,
-	options: CreateComputedExpressionOptions = {}
+	options: CreateComputedExpressionOptions<Type> = {}
 ): ComputedExpression<Type> => {
-	const { contextNode, evaluator, root, scope } = context;
-	const { expression, isTranslated, resultType } = dependentExpression;
-	const dependencyReferences = Array.from(dependentExpression.dependencyReferences);
-	const evaluateExpression = expressionEvaluator(evaluator, contextNode, resultType, expression);
+	return context.scope.runTask(() => {
+		const { contextNode, evaluator } = context;
+		const { expression, isTranslated, resultType } = dependentExpression;
+		const evaluatePreInitializationDefaultValue = () => {
+			return options?.defaultValue ?? defaultEvaluationsByType[resultType];
+		};
+		const evaluateExpression = expressionEvaluator(evaluator, resultType, expression, {
+			contextNode,
+		});
 
-	return scope.runTask(() => {
 		if (isConstantExpression(expression)) {
 			return createMemo(evaluateExpression);
 		}
 
-		const { arbitraryDependencies = [] } = options;
-
-		const getReferencedDependencies = createMemo(() => {
-			return dependencyReferences.flatMap((reference) => {
-				return context.getSubscribableDependenciesByReference(reference) ?? [];
-			});
-		});
-
 		return createMemo(() => {
-			if (isTranslated) {
-				root.subscribe();
+			if (!context.isAttached()) {
+				return evaluatePreInitializationDefaultValue();
 			}
 
-			arbitraryDependencies.forEach((dependency) => {
-				dependency.subscribe();
-			});
-
-			getReferencedDependencies().forEach((dependency) => {
-				dependency.subscribe();
-			});
+			if (isTranslated) {
+				context.getActiveLanguage();
+			}
 
 			return evaluateExpression();
 		});

package/src/lib/reactivity/createInstanceValueState.ts

@@ -0,0 +1,216 @@
+import type { Signal } from 'solid-js';
+import { createComputed, createMemo, createSignal, untrack } from 'solid-js';
+import { ErrorProductionDesignPendingError } from '../../error/ErrorProductionDesignPendingError.ts';
+import type { InstanceValueContext } from '../../instance/internal-api/InstanceValueContext.ts';
+import type { BindComputationExpression } from '../../parse/expression/BindComputationExpression.ts';
+import { createComputedExpression } from './createComputedExpression.ts';
+import type { SimpleAtomicState, SimpleAtomicStateSetter } from './types.ts';
+
+type InitialValueSource = 'FORM_DEFAULT' | 'PRIMARY_INSTANCE';
+
+/**
+ * @todo {@link InitialValueSource} naming leaves a lot to be desired. As described in {@link InstanceValueStateOptions.initialValueSource}, this check (for now) will effectively answer the question: "are we **NOT** editing instance state (e.g. a submission)?". This answer, in turn, determines whether to {@link setPreloadUIDValue}
+ */
+const isInstanceFirstLoad = (valueSource?: InitialValueSource) => {
+	return valueSource === 'FORM_DEFAULT';
+};
+
+export interface InstanceValueStateOptions {
+	/**
+	 * Specifies the source of a {@link createInstanceValueState} signal's initial
+	 * value state, where:
+	 *
+	 * - 'FORM_DEFAULT': Derives the initial state from the form's definition of
+	 *   the node itself. This is the default option, appropriate when
+	 *   initializing a form without additional primary instance data. In 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}. This option should be
+	 *   specified when initializing a form with existing primary instance data,
+	 *   such as when editing a previous submission.
+	 *
+	 * @default 'FORM_DEFAULT'
+	 *
+	 * Specifies whether a {@link createInstanceValueState} signal's initial state
+	 * should be derived from the current text content of the
+	 * {@link ValueNode.contextNode | primary instance DOM state}.
+	 */
+	readonly initialValueSource?: InitialValueSource;
+}
+
+const getInitialValue = (
+	context: InstanceValueContext,
+	options: InstanceValueStateOptions
+): string => {
+	const { initialValueSource = 'FORM_DEFAULT' } = options;
+
+	if (initialValueSource === 'FORM_DEFAULT') {
+		const { defaultValue } = context.definition;
+
+		return context.decodeInstanceValue(defaultValue);
+	}
+
+	throw new ErrorProductionDesignPendingError('Edit implementation pending');
+};
+
+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: InstanceValueContext,
+	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: InstanceValueContext,
+	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 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: InstanceValueContext,
+	valueState: RelevantValueState,
+	options: InstanceValueStateOptions
+): void => {
+	const { preload } = context.definition.bind;
+
+	if (preload?.type !== 'uid' || !isInstanceFirstLoad(options?.initialValueSource)) {
+		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: InstanceValueContext,
+	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 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
+ * - prevents downstream writes to nodes in a readonly state
+ */
+export const createInstanceValueState = (
+	context: InstanceValueContext,
+	options: InstanceValueStateOptions = {}
+): InstanceValueState => {
+	return context.scope.runTask(() => {
+		const initialValue = getInitialValue(context, options);
+		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, options);
+
+		const { calculate } = context.definition.bind;
+
+		if (calculate != null) {
+			const [, setValue] = relevantValueState;
+
+			createCalculation(context, setValue, calculate);
+		}
+
+		return guardDownstreamReadonlyWrites(context, relevantValueState);
+	});
+};