@getodk/xforms-engine 0.1.0

package/src/instance/internal-api/SubscribableDependency.ts

@@ -0,0 +1,61 @@
+import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
+import type { EvaluationContext } from './EvaluationContext.ts';
+
+/**
+ * Provides a common interface to explicitly establish a reactive subscription
+ * to a form node, regardless of which node-specific details might trigger
+ * reactive updates. This is primarily intended for use in coordination with a
+ * node's {@link EvaluationContext} interface, so that computed expression
+ * evaluations can be re-executed when their dependencies update, without
+ * requiring a given evaluation to handle node-specific logic to determine
+ * when/whether updates have occurred.
+ *
+ * @example Given a form with these bindings:
+ *
+ * ```xml
+ * <bind nodeset="/data/field-1" />
+ * <bind nodeset="/data/field-2" type="int" />
+ * <bind nodeset="/data/group-a" relevant="/data/field-1 != ''" />
+ * <bind nodeset="/data/group-a/field-a-1" calculate="/data/field-2 * 2" />
+ * ```
+ *
+ * The field `/data/group-a/field-a-1`'s calculate has two dependencies:
+ *
+ * - `/data-field-2` (explicit)
+ * - `/data/group-a` (implicit: non-relevance is inherited)
+ *
+ * (This is an oversimplification, but it helps to illustrate the concept.)
+ *
+ * The first dependency's subscription is clearly concerned with that leaf
+ * node's value. In which case, that node's `subscribe` method should react to
+ * updates to its value (e.g. its `currentState.value` or the internal reactive
+ * representation thereof).
+ *
+ * Whereas the second dependency has no value (no parent nodes do); instead, the
+ * subscription would be concerned with that node's relevance. In which case,
+ * that node's `subscribe` method should react to updates to its relevance state
+ * (e.g. its `currentState.relevant` or the internal reactive represeentation
+ * thereof).
+ *
+ * @example Given a form with:
+ *
+ * ```xml
+ * <!-- model -->
+ * <bind nodeset="/data/repeat-a/field-a-1" calculate="position(..)" />
+ * <!-- body -->
+ * <repeat nodeset="/data/repeat-a" />
+ * ```
+ *
+ * The field `/data/repeat-a/field-a-1` has a dependency on its containing
+ * repeat instance. That node also doesn't have a value, and here the dynamic
+ * aspect of the dependency is the node's current position. Here the node's
+ * `subscribe` method should react to changes in its position (likely indirectly
+ * by reading its `contextReference`).
+ *
+ * @see {@link EvaluationContext}
+ * @see {@link EvaluationContext.contextReference}
+ */
+export interface SubscribableDependency {
+	readonly scope: ReactiveScope;
+	readonly subscribe: VoidFunction;
+}

package/src/instance/internal-api/TranslationContext.ts

@@ -0,0 +1,5 @@
+import type { ActiveLanguage } from '../../index.ts';
+
+export interface TranslationContext {
+	get activeLanguage(): ActiveLanguage;
+}

package/src/instance/internal-api/ValueContext.ts

@@ -0,0 +1,27 @@
+import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
+import type { BindComputation } from '../../model/BindComputation.ts';
+import type { EvaluationContext } from './EvaluationContext.ts';
+
+export type InstanceValue = string;
+
+interface ValueContextDefinitionBind {
+	readonly calculate: BindComputation<'calculate'> | null;
+	readonly readonly: BindComputation<'readonly'>;
+}
+
+export interface ValueContextDefinition {
+	readonly bind: ValueContextDefinitionBind;
+	readonly defaultValue: InstanceValue;
+}
+
+export interface ValueContext<RuntimeValue> extends EvaluationContext {
+	readonly scope: ReactiveScope;
+	readonly definition: ValueContextDefinition;
+	readonly contextNode: Element;
+
+	get isReadonly(): boolean;
+	get isRelevant(): boolean;
+
+	readonly encodeValue: (this: unknown, runtimeValue: RuntimeValue) => InstanceValue;
+	readonly decodeValue: (this: unknown, instanceValue: InstanceValue) => RuntimeValue;
+}

package/src/instance/resource.ts

@@ -0,0 +1,75 @@
+import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
+import { getBlobText } from '@getodk/common/lib/web-compat/blob.ts';
+import type { FetchResource, FetchResourceResponse } from '../client/EngineConfig.ts';
+import type { FormResource } from '../client/index.ts';
+
+export type { FetchResource, FetchResourceResponse, FormResource };
+
+export interface ResourceOptions {
+	readonly fetchResource: FetchResource;
+}
+
+const fetchTextFromURL = async (resource: URL, options: ResourceOptions): Promise<string> => {
+	const response = await options.fetchResource(resource);
+
+	return response.text();
+};
+
+const resourceXMLPrefix = '<';
+
+type ResourceXMLPrefix = typeof resourceXMLPrefix;
+
+type ResourceXML = `${ResourceXMLPrefix}${string}`;
+
+class InvalidSourceXMLError extends Error {
+	constructor(readonly resourceText: string) {
+		super('Source text is not XML');
+	}
+}
+
+const isXML = (resourceText: string): resourceText is ResourceXML => {
+	return resourceText.startsWith(resourceXMLPrefix);
+};
+
+type AssertResourceTextIsXML = (resourceText: string) => asserts resourceText is ResourceXML;
+
+const assertResourceTextIsXML: AssertResourceTextIsXML = (resourceText) => {
+	if (!isXML(resourceText)) {
+		throw new InvalidSourceXMLError(resourceText);
+	}
+};
+
+class InvalidFormResourceError extends Error {
+	constructor(readonly resource: FormResource) {
+		super('Invalid form resource');
+	}
+}
+
+export const retrieveSourceXMLResource = async (
+	resource: FormResource,
+	options: ResourceOptions
+): Promise<ResourceXML> => {
+	let text: string;
+
+	if (resource instanceof URL) {
+		text = await fetchTextFromURL(resource, options);
+	} else if (resource instanceof Blob) {
+		text = await getBlobText(resource);
+	} else if (typeof resource === 'string') {
+		const trimmed = resource.trim();
+
+		if (isXML(trimmed)) {
+			text = trimmed;
+		} else if (URL.canParse(trimmed)) {
+			text = await fetchTextFromURL(new URL(trimmed), options);
+		} else {
+			throw new InvalidFormResourceError(trimmed);
+		}
+	} else {
+		throw new UnreachableError(resource);
+	}
+
+	assertResourceTextIsXML(text);
+
+	return text;
+};

package/src/instance/text/FormattedTextStub.ts

@@ -0,0 +1,8 @@
+export const FormattedTextStub = new Proxy({} as Record<PropertyKey, unknown>, {
+	get() {
+		throw new TypeError('Not implemented');
+	},
+	set() {
+		return false;
+	},
+});

package/src/instance/text/TextChunk.ts

@@ -0,0 +1,20 @@
+import type { ActiveLanguage } from '../../client/FormLanguage.ts';
+import type { TextChunk as ClientTextChunk, TextChunkSource } from '../../client/TextRange.ts';
+import type { TranslationContext } from '../internal-api/TranslationContext.ts';
+import { FormattedTextStub } from './FormattedTextStub.ts';
+
+export class TextChunk implements ClientTextChunk {
+	get formatted() {
+		return FormattedTextStub;
+	}
+
+	get language(): ActiveLanguage {
+		return this.context.activeLanguage;
+	}
+
+	constructor(
+		readonly context: TranslationContext,
+		readonly source: TextChunkSource,
+		readonly asString: string
+	) {}
+}

package/src/instance/text/TextRange.ts

@@ -0,0 +1,23 @@
+import type { TextRange as ClientTextRange, TextChunk } from '../../client/TextRange.ts';
+import { FormattedTextStub } from './FormattedTextStub.ts';
+
+export type TextRole = 'hint' | 'label';
+
+export class TextRange<Role extends TextRole> implements ClientTextRange<Role> {
+	*[Symbol.iterator]() {
+		yield* this.chunks;
+	}
+
+	get formatted() {
+		return FormattedTextStub;
+	}
+
+	get asString(): string {
+		return this.chunks.map((chunk) => chunk.asString).join('');
+	}
+
+	constructor(
+		readonly role: Role,
+		protected readonly chunks: readonly TextChunk[]
+	) {}
+}

package/src/lib/dom/query.ts

@@ -0,0 +1,49 @@
+import { ScopedElementLookup } from '@getodk/common/lib/dom/compatibility.ts';
+import type {
+	KnownAttributeLocalNamedElement,
+	LocalNamedElement,
+} from '@getodk/common/types/dom.ts';
+import type { SelectElement } from '../../body/control/select/SelectDefinition';
+
+const hintLookup = new ScopedElementLookup(':scope > hint', 'hint');
+const itemLookup = new ScopedElementLookup(':scope > item', 'item');
+const itemsetLookup = new ScopedElementLookup(':scope > itemset[nodeset]', 'itemset[nodeset]');
+const labelLookup = new ScopedElementLookup(':scope > label', 'label');
+const repeatLookup = new ScopedElementLookup(':scope > repeat[nodeset]', 'repeat[nodeset]');
+const valueLookup = new ScopedElementLookup(':scope > value', 'value');
+
+export interface HintElement extends LocalNamedElement<'hint'> {}
+
+export interface ItemElement extends LocalNamedElement<'item'> {}
+
+export interface ItemsetElement extends KnownAttributeLocalNamedElement<'itemset', 'nodeset'> {}
+
+export interface LabelElement extends LocalNamedElement<'label'> {}
+
+export interface RepeatElement extends KnownAttributeLocalNamedElement<'repeat', 'nodeset'> {}
+
+export interface ValueElement extends LocalNamedElement<'value'> {}
+
+export const getHintElement = (parent: Element): HintElement | null => {
+	return hintLookup.getElement<HintElement>(parent);
+};
+
+export const getItemElements = (parent: SelectElement): readonly ItemElement[] => {
+	return Array.from(itemLookup.getElements<ItemElement>(parent));
+};
+
+export const getItemsetElement = (parent: Element): ItemsetElement | null => {
+	return itemsetLookup.getElement<ItemsetElement>(parent);
+};
+
+export const getLabelElement = (parent: Element): LabelElement | null => {
+	return labelLookup.getElement<LabelElement>(parent);
+};
+
+export const getRepeatElement = (parent: Element): RepeatElement | null => {
+	return repeatLookup.getElement<RepeatElement>(parent);
+};
+
+export const getValueElement = (parent: ItemElement | ItemsetElement): ValueElement | null => {
+	return valueLookup.getElement<ValueElement>(parent);
+};

package/src/lib/reactivity/createChildrenState.ts

@@ -0,0 +1,60 @@
+import { createMemo, createSignal, type Accessor, type Setter, type Signal } from 'solid-js';
+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';
+import type { EngineState } from './node-state/createEngineState.ts';
+
+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[]>;
+}
+
+/**
+ * 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}
+ *
+ * This state is used, in tandem with {@link materializeCurrentStateChildren},
+ * to ensure children in **client-facing** state are not written into nested
+ * {@link OpaqueReactiveObjectFactory} calls.
+ *
+ * The produced {@link ChildrenState.children} (and its get/set convenience
+ * methods) signal is intended to be used to store the engine's children state,
+ * and update that state when appropriate (when appending children of any parent
+ * node during form initialization, and when appending repeat instances and
+ * their descendants subsequently during a form session).
+ *
+ * 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.
+ *
+ * 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
+ * {@link materializeCurrentStateChildren}.
+ */
+export const createChildrenState = <Parent extends AnyParentNode, Child extends AnyChildNode>(
+	parent: Parent
+): ChildrenState<Child> => {
+	return parent.scope.runTask(() => {
+		const children = createSignal<readonly Child[]>([]);
+		const [getChildren, setChildren] = children;
+		const childIds = createMemo((): readonly NodeID[] => {
+			return getChildren().map((child) => child.nodeId);
+		});
+
+		return {
+			children,
+			getChildren,
+			setChildren,
+			childIds,
+		};
+	});
+};

package/src/lib/reactivity/createComputedExpression.ts

@@ -0,0 +1,114 @@
+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 {
+	DependentExpression,
+	DependentExpressionResultType,
+} from '../../expression/DependentExpression.ts';
+import type { EvaluationContext } from '../../instance/internal-api/EvaluationContext.ts';
+import type { SubscribableDependency } from '../../instance/internal-api/SubscribableDependency.ts';
+
+interface ComputedExpressionResults {
+	readonly boolean: boolean;
+	readonly nodes: Node[];
+	readonly string: string;
+}
+
+// prettier-ignore
+type EvaluatedExpression<
+	Type extends DependentExpressionResultType
+> = ComputedExpressionResults[Type];
+
+// prettier-ignore
+type ExpressionEvaluator<
+	Type extends DependentExpressionResultType
+> = () => EvaluatedExpression<Type>
+
+const expressionEvaluator = <Type extends DependentExpressionResultType>(
+	evaluator: XFormsXPathEvaluator,
+	contextNode: Node,
+	type: Type,
+	expression: string
+): ExpressionEvaluator<Type> => {
+	const options = { contextNode };
+
+	switch (type) {
+		case 'boolean':
+			return (() => {
+				return evaluator.evaluateBoolean(expression, options);
+			}) as ExpressionEvaluator<Type>;
+
+		case 'nodes':
+			return (() => {
+				return evaluator.evaluateNodes(expression, options);
+			}) as ExpressionEvaluator<Type>;
+
+		case 'string':
+			return (() => {
+				return evaluator.evaluateString(expression, options);
+			}) as ExpressionEvaluator<Type>;
+
+		default:
+			throw new UnreachableError(type);
+	}
+};
+
+/**
+ * Determines if an XPath expression will always produce the same value.
+ *
+ * @todo There are quite a few more cases than this, and it also likely belongs
+ * in another `lib` module.
+ */
+const isConstantExpression = (expression: string): boolean => {
+	const normalized = expression.replaceAll(/\s/g, '');
+
+	return normalized === 'true()' || normalized === 'false()';
+};
+
+// prettier-ignore
+type ComputedExpression<Type extends DependentExpressionResultType> = Accessor<
+	EvaluatedExpression<Type>
+>;
+
+export const createComputedExpression = <Type extends DependentExpressionResultType>(
+	context: EvaluationContext,
+	dependentExpression: DependentExpression<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 scope.runTask(() => {
+		if (isConstantExpression(expression)) {
+			return createMemo(evaluateExpression);
+		}
+
+		const getReferencedDependencies = createMemo(() => {
+			return dependencyReferences.flatMap((reference) => {
+				return context.getSubscribableDependencyByReference(reference) ?? [];
+			});
+		});
+
+		let getDependencies: Accessor<readonly SubscribableDependency[]>;
+
+		if (isTranslated) {
+			getDependencies = createMemo(() => {
+				return [root, ...getReferencedDependencies()];
+			});
+		} else {
+			getDependencies = getReferencedDependencies;
+		}
+
+		return createMemo(() => {
+			const dependencies = getDependencies();
+
+			dependencies.forEach((dependency) => {
+				dependency.subscribe();
+			});
+
+			return evaluateExpression();
+		});
+	});
+};

package/src/lib/reactivity/createSelectItems.ts

@@ -0,0 +1,163 @@
+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 { ItemDefinition } from '../../body/control/select/ItemDefinition.ts';
+import type { ItemsetDefinition } from '../../body/control/select/ItemsetDefinition.ts';
+import type { SelectItem } from '../../index.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 type { TextRange } from '../../instance/text/TextRange.ts';
+import { createComputedExpression } from './createComputedExpression.ts';
+import type { ReactiveScope } from './scope.ts';
+import { createTextRange } from './text/createTextRange.ts';
+
+const createSelectItemLabel = (
+	context: EvaluationContext,
+	definition: ItemDefinition
+): Accessor<TextRange<'label'>> => {
+	const { label, value } = definition;
+
+	return createTextRange(context, 'label', label, {
+		fallbackValue: value,
+	});
+};
+
+const createTranslatedStaticSelectItems = (
+	selectField: SelectField,
+	items: readonly ItemDefinition[]
+): Accessor<readonly SelectItem[]> => {
+	return selectField.scope.runTask(() => {
+		const labeledItems = items.map((item) => {
+			const { value } = item;
+			const label = createSelectItemLabel(selectField, item);
+
+			return () => ({
+				value,
+				label: label(),
+			});
+		});
+
+		return createMemo(() => {
+			return labeledItems.map((item) => item());
+		});
+	});
+};
+
+class ItemsetItemEvaluationContext implements EvaluationContext {
+	readonly scope: ReactiveScope;
+	readonly evaluator: XFormsXPathEvaluator;
+	readonly root: EvaluationContextRoot;
+
+	get contextReference(): string {
+		return this.selectField.contextReference;
+	}
+
+	constructor(
+		private readonly selectField: SelectField,
+		readonly contextNode: Node
+	) {
+		this.scope = selectField.scope;
+		this.evaluator = selectField.evaluator;
+		this.root = selectField.root;
+	}
+
+	getSubscribableDependencyByReference(reference: string): SubscribableDependency | null {
+		return this.selectField.getSubscribableDependencyByReference(reference);
+	}
+}
+
+const createSelectItemsetItemLabel = (
+	context: EvaluationContext,
+	definition: ItemsetDefinition,
+	itemValue: Accessor<string>
+): Accessor<TextRange<'label'>> => {
+	const { label } = definition;
+
+	if (label == null) {
+		return createMemo(() => {
+			const value = itemValue();
+			const staticValueLabel = createTextRange(context, 'label', label, {
+				fallbackValue: value,
+			});
+
+			return staticValueLabel();
+		});
+	}
+
+	return createTextRange(context, 'label', label);
+};
+
+interface ItemsetItem {
+	label(): TextRange<'label'>;
+	value(): string;
+}
+
+const createItemsetItems = (
+	selectField: SelectField,
+	itemset: ItemsetDefinition
+): Accessor<readonly ItemsetItem[]> => {
+	return selectField.scope.runTask(() => {
+		const itemNodes = createComputedExpression(selectField, itemset.nodes);
+		const itemsCache = new UpsertableMap<Node, ItemsetItem>();
+
+		return createMemo(() => {
+			return itemNodes().map((itemNode) => {
+				return itemsCache.upsert(itemNode, () => {
+					const context = new ItemsetItemEvaluationContext(selectField, itemNode);
+					const value = createComputedExpression(context, itemset.value);
+					const label = createSelectItemsetItemLabel(context, itemset, value);
+
+					return {
+						label,
+						value,
+					};
+				});
+			});
+		});
+	});
+};
+
+const createItemset = (
+	selectField: SelectField,
+	itemset: ItemsetDefinition
+): Accessor<readonly SelectItem[]> => {
+	return selectField.scope.runTask(() => {
+		const itemsetItems = createItemsetItems(selectField, itemset);
+
+		return createMemo(() => {
+			return itemsetItems().map((item) => {
+				return {
+					label: item.label(),
+					value: item.value(),
+				};
+			});
+		});
+	});
+};
+
+/**
+ * Creates a reactive computation of a {@link SelectField}'s
+ * {@link SelectItem}s, in support of the field's `valueOptions`.
+ *
+ * - Selects defined with static `<item>`s will compute to an corresponding
+ *   static list of items.
+ * - Selects defined with a computed `<itemset>` will compute to a reactive list
+ *   of items.
+ * - Items of both will produce {@link SelectItem.label | labels} reactive to
+ *   their appropriate dependencies (whether relative to the itemset item node,
+ *   referencing a form's `itext` translations, etc).
+ */
+export const createSelectItems = (selectField: SelectField): Accessor<readonly SelectItem[]> => {
+	const { items, itemset } = selectField.definition.bodyElement;
+
+	if (itemset == null) {
+		return createTranslatedStaticSelectItems(selectField, items);
+	}
+
+	return createItemset(selectField, itemset);
+};