@getodk/xforms-engine 0.1.0

package/src/instance/Root.ts

@@ -0,0 +1,264 @@
+import type { XFormsXPathEvaluator } from '@getodk/xpath';
+import type { Accessor, Signal } from 'solid-js';
+import { createSignal } from 'solid-js';
+import type { XFormDOM } from '../XFormDOM.ts';
+import type { ActiveLanguage, FormLanguage, FormLanguages } from '../client/FormLanguage.ts';
+import type { RootNode } from '../client/RootNode.ts';
+import type { ChildrenState } from '../lib/reactivity/createChildrenState.ts';
+import { createChildrenState } from '../lib/reactivity/createChildrenState.ts';
+import type { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
+import { materializeCurrentStateChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
+import type { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
+import type { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
+import type { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
+import { createSharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
+import type { RootDefinition } from '../model/RootDefinition.ts';
+import { InstanceNode } from './abstract/InstanceNode.ts';
+import { buildChildren } from './children.ts';
+import type { GeneralChildNode } from './hierarchy.ts';
+import type { NodeID } from './identity.ts';
+import type { EvaluationContext, EvaluationContextRoot } from './internal-api/EvaluationContext.ts';
+import type { InstanceConfig } from './internal-api/InstanceConfig.ts';
+import type { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
+import type { TranslationContext } from './internal-api/TranslationContext.ts';
+
+interface RootStateSpec {
+	readonly reference: string;
+	readonly readonly: boolean;
+	readonly relevant: boolean;
+	readonly required: boolean;
+	readonly label: null;
+	readonly hint: null;
+	readonly children: Accessor<readonly NodeID[]>;
+	readonly valueOptions: null;
+	readonly value: null;
+
+	// Root-specific
+	readonly activeLanguage: Signal<ActiveLanguage>;
+}
+
+// Subset of types expected from evaluator
+interface ItextTranslations {
+	getActiveLanguage(): string | null;
+	getLanguages(): readonly string[];
+}
+
+interface InitialLanguageState {
+	readonly defaultLanguage: ActiveLanguage;
+	readonly languages: FormLanguages;
+}
+
+// TODO: it's really very silly that the XPath evaluator is the current
+// definitional source of truth for translation stuff... even though it currently makes sense that that's where it's first derived.
+const getInitialLanguageState = (translations: ItextTranslations): InitialLanguageState => {
+	const activeLanguageName = translations.getActiveLanguage();
+
+	if (activeLanguageName == null) {
+		const defaultLanguage: ActiveLanguage = {
+			isSyntheticDefault: true,
+			language: '',
+		};
+		const languages = [defaultLanguage] satisfies FormLanguages;
+
+		return {
+			defaultLanguage,
+			languages,
+		};
+	}
+
+	const languageNames = translations.getLanguages();
+
+	const inactiveLanguages = languageNames
+		.filter((languageName) => {
+			return languageName !== activeLanguageName;
+		})
+		.map((language): FormLanguage => {
+			return { language };
+		});
+
+	const languages = [
+		{ language: activeLanguageName } satisfies FormLanguage,
+
+		...inactiveLanguages,
+	] satisfies FormLanguages;
+	const [defaultLanguage] = languages;
+
+	return {
+		defaultLanguage,
+		languages,
+	};
+};
+
+export class Root
+	extends InstanceNode<RootDefinition, RootStateSpec, GeneralChildNode>
+	implements
+		RootNode,
+		EvaluationContext,
+		EvaluationContextRoot,
+		SubscribableDependency,
+		TranslationContext
+{
+	static async initialize(
+		xformDOM: XFormDOM,
+		definition: RootDefinition,
+		engineConfig: InstanceConfig
+	): Promise<Root> {
+		const instance = new Root(xformDOM, definition, engineConfig);
+
+		await instance.formStateInitialized();
+
+		return instance;
+	}
+
+	private readonly childrenState: ChildrenState<GeneralChildNode>;
+
+	// InstanceNode
+	protected readonly state: SharedNodeState<RootStateSpec>;
+	protected readonly engineState: EngineState<RootStateSpec>;
+
+	// RootNode
+	readonly nodeType = 'root';
+
+	readonly currentState: MaterializedChildren<CurrentState<RootStateSpec>, GeneralChildNode>;
+
+	protected readonly instanceDOM: XFormDOM;
+
+	// BaseNode
+	readonly root = this;
+
+	// EvaluationContext
+	readonly evaluator: XFormsXPathEvaluator;
+
+	private readonly rootReference: string;
+
+	override get contextReference(): string {
+		return this.rootReference;
+	}
+
+	readonly contextNode: Element;
+
+	// RootNode
+	override readonly parent = null;
+
+	readonly languages: FormLanguages;
+
+	// TranslationContext
+	get activeLanguage(): ActiveLanguage {
+		return this.engineState.activeLanguage;
+	}
+
+	protected constructor(
+		xformDOM: XFormDOM,
+		definition: RootDefinition,
+		engineConfig: InstanceConfig
+	) {
+		super(engineConfig, null, definition);
+
+		const childrenState = createChildrenState<Root, GeneralChildNode>(this);
+
+		this.childrenState = childrenState;
+
+		const reference = definition.nodeset;
+
+		this.rootReference = reference;
+
+		const instanceDOM = xformDOM.createInstance();
+		const evaluator = instanceDOM.primaryInstanceEvaluator;
+		const { translations } = evaluator;
+		const { defaultLanguage, languages } = getInitialLanguageState(translations);
+		const state = createSharedNodeState(
+			this.scope,
+			{
+				activeLanguage: createSignal<ActiveLanguage>(defaultLanguage),
+				reference,
+				label: null,
+				hint: null,
+				readonly: false,
+				relevant: true,
+				required: false,
+				valueOptions: null,
+				value: null,
+				children: childrenState.childIds,
+			},
+			{
+				clientStateFactory: engineConfig.stateFactory,
+			}
+		);
+
+		this.state = state;
+		this.engineState = state.engineState;
+		this.currentState = materializeCurrentStateChildren(state.currentState, childrenState);
+
+		const contextNode = instanceDOM.xformDocument.createElement(definition.nodeName);
+
+		instanceDOM.primaryInstanceRoot.replaceWith(contextNode);
+
+		this.evaluator = evaluator;
+		this.contextNode = contextNode;
+		this.instanceDOM = instanceDOM;
+		this.languages = languages;
+
+		childrenState.setChildren(buildChildren(this));
+	}
+
+	/**
+	 * Waits until form state is fully initialized.
+	 *
+	 * As much as possible, all instance state computations are implemented so
+	 * that they complete synchronously.
+	 *
+	 * There is currently one exception: because instance nodes may form
+	 * computation dependencies into their descendants as well as their ancestors,
+	 * there is an allowance **during form initialization only** to account for
+	 * this chicken/egg scenario. Note that this allowance is intentionally,
+	 * strictly limited: if form state initialization is not resolved within a
+	 * single microtask tick we throw/reject.
+	 *
+	 * All subsequent computations are always performed synchronously (and we will
+	 * use tests to validate this, by utilizing the synchronously returned `Root`
+	 * state from client-facing write interfaces).
+	 */
+	async formStateInitialized(): Promise<void> {
+		await new Promise<void>((resolve) => {
+			queueMicrotask(resolve);
+		});
+
+		if (!this.isStateInitialized()) {
+			throw new Error(
+				'Form state initialization failed to complete in a single frame. Has some aspect of reactive computation been made asynchronous by mistake?'
+			);
+		}
+	}
+
+	// InstanceNode
+	protected computeReference(_parent: null, definition: RootDefinition): string {
+		return definition.nodeset;
+	}
+
+	getChildren(): readonly GeneralChildNode[] {
+		return this.childrenState.getChildren();
+	}
+
+	// RootNode
+	setLanguage(language: FormLanguage): Root {
+		const activeLanguage = this.languages.find((formLanguage) => {
+			return formLanguage.language === language.language;
+		});
+
+		if (activeLanguage == null) {
+			throw new Error(`Language "${language.language}" not available`);
+		}
+
+		this.evaluator.translations.setActiveLanguage(activeLanguage.language);
+		this.state.setProperty('activeLanguage', activeLanguage);
+
+		return this;
+	}
+
+	// SubscribableDependency
+	override subscribe(): void {
+		super.subscribe();
+
+		this.engineState.activeLanguage;
+	}
+}

package/src/instance/SelectField.ts

@@ -0,0 +1,204 @@
+import { xmlXPathWhitespaceSeparatedList } from '@getodk/common/lib/string/whitespace.ts';
+import type { Accessor } from 'solid-js';
+import { untrack } from 'solid-js';
+import type { AnySelectDefinition } from '../body/control/select/SelectDefinition.ts';
+import type { SelectItem, SelectNode } from '../client/SelectNode.ts';
+import type { TextRange } from '../index.ts';
+import { createSelectItems } from '../lib/reactivity/createSelectItems.ts';
+import { createValueState } from '../lib/reactivity/createValueState.ts';
+import type { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
+import type { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
+import type { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
+import { createSharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
+import { createFieldHint } from '../lib/reactivity/text/createFieldHint.ts';
+import { createNodeLabel } from '../lib/reactivity/text/createNodeLabel.ts';
+import type { SimpleAtomicState } from '../lib/reactivity/types.ts';
+import type { ValueNodeDefinition } from '../model/ValueNodeDefinition.ts';
+import type { Root } from './Root.ts';
+import type { DescendantNodeStateSpec } from './abstract/DescendantNode.ts';
+import { DescendantNode } from './abstract/DescendantNode.ts';
+import type { GeneralParentNode } from './hierarchy.ts';
+import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
+import type { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
+import type { ValueContext } from './internal-api/ValueContext.ts';
+
+export interface SelectFieldDefinition extends ValueNodeDefinition {
+	readonly bodyElement: AnySelectDefinition;
+}
+
+interface SelectFieldStateSpec extends DescendantNodeStateSpec<readonly SelectItem[]> {
+	readonly label: Accessor<TextRange<'label'> | null>;
+	readonly hint: Accessor<TextRange<'hint'> | null>;
+	readonly children: null;
+	readonly value: SimpleAtomicState<readonly SelectItem[]>;
+	readonly valueOptions: Accessor<readonly SelectItem[]>;
+}
+
+export class SelectField
+	extends DescendantNode<SelectFieldDefinition, SelectFieldStateSpec, null>
+	implements
+		SelectNode,
+		EvaluationContext,
+		SubscribableDependency,
+		ValueContext<readonly SelectItem[]>
+{
+	private readonly selectExclusive: boolean;
+
+	// InstanceNode
+	protected readonly state: SharedNodeState<SelectFieldStateSpec>;
+	protected override engineState: EngineState<SelectFieldStateSpec>;
+
+	// SelectNode
+	readonly nodeType = 'select';
+
+	readonly currentState: CurrentState<SelectFieldStateSpec>;
+
+	// ValueContext
+	readonly encodeValue = (runtimeValue: readonly SelectItem[]): string => {
+		const itemValues = new Set(runtimeValue.map(({ value }) => value));
+
+		return Array.from(itemValues).join(' ');
+	};
+
+	readonly decodeValue = (instanceValue: string): readonly SelectItem[] => {
+		return this.scope.runTask(() => {
+			const values = xmlXPathWhitespaceSeparatedList(instanceValue, {
+				ignoreEmpty: true,
+			});
+
+			const items = this.getSelectItemsByValue();
+
+			return values
+				.map((value) => {
+					return items.get(value);
+				})
+				.filter((item): item is SelectItem => {
+					return item != null;
+				});
+		});
+	};
+
+	protected readonly getValueOptions: Accessor<readonly SelectItem[]>;
+
+	constructor(parent: GeneralParentNode, definition: SelectFieldDefinition) {
+		super(parent, definition);
+
+		this.selectExclusive = definition.bodyElement.type === 'select1';
+
+		const valueOptions = createSelectItems(this);
+
+		this.getValueOptions = valueOptions;
+
+		const state = createSharedNodeState(
+			this.scope,
+			{
+				...this.buildSharedStateSpec(parent, definition),
+
+				label: createNodeLabel(this, definition),
+				hint: createFieldHint(this, definition),
+				children: null,
+				value: createValueState(this),
+				valueOptions,
+			},
+			{
+				clientStateFactory: this.engineConfig.stateFactory,
+			}
+		);
+
+		this.state = state;
+		this.engineState = state.engineState;
+		this.currentState = state.currentState;
+	}
+
+	protected getSelectItemsByValue(
+		valueOptions: readonly SelectItem[] = this.getValueOptions()
+	): ReadonlyMap<string, SelectItem> {
+		return new Map(
+			valueOptions.map((item) => {
+				return [item.value, item];
+			})
+		);
+	}
+
+	protected computeReference(parent: GeneralParentNode): string {
+		return this.computeChildStepReference(parent);
+	}
+
+	protected updateSelectedItemValues(values: readonly string[]) {
+		const itemsByValue = untrack(() => this.getSelectItemsByValue());
+
+		const items = values.flatMap((value) => {
+			const item = itemsByValue.get(value);
+
+			if (item == null) {
+				return [];
+			}
+
+			return item ?? [];
+		});
+
+		this.state.setProperty('value', items);
+	}
+
+	protected setSelectedItemValue(value: string | null) {
+		if (value == null) {
+			this.state.setProperty('value', []);
+
+			return;
+		}
+
+		this.updateSelectedItemValues([value]);
+	}
+
+	// SelectNode
+	select(selectedItem: SelectItem): Root {
+		const { engineState, root } = this;
+
+		if (this.selectExclusive) {
+			this.setSelectedItemValue(selectedItem.value);
+
+			return root;
+		}
+
+		const currentValues = engineState.value.map(({ value }) => {
+			return value;
+		});
+
+		const selectedValue = selectedItem.value;
+
+		if (currentValues.includes(selectedValue)) {
+			return root;
+		}
+
+		this.updateSelectedItemValues(currentValues.concat(selectedValue));
+
+		return root;
+	}
+
+	deselect(deselectedItem: SelectItem): Root {
+		const { engineState, root } = this;
+
+		const currentValues = engineState.value.map(({ value }) => {
+			return value;
+		});
+
+		const selectedValue = deselectedItem.value;
+
+		if (!currentValues.includes(selectedValue)) {
+			return root;
+		}
+
+		const updatedValues = currentValues.filter((value) => {
+			return value !== selectedValue;
+		});
+
+		this.updateSelectedItemValues(updatedValues);
+
+		return root;
+	}
+
+	// InstanceNode
+	getChildren(): readonly [] {
+		return [];
+	}
+}

package/src/instance/StringField.ts

@@ -0,0 +1,93 @@
+import { identity } from '@getodk/common/lib/identity.ts';
+import type { Accessor } from 'solid-js';
+import type { InputDefinition } from '../body/control/InputDefinition.ts';
+import type { StringNode } from '../client/StringNode.ts';
+import type { TextRange } from '../index.ts';
+import { createValueState } from '../lib/reactivity/createValueState.ts';
+import type { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
+import type { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
+import type { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
+import { createSharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
+import { createFieldHint } from '../lib/reactivity/text/createFieldHint.ts';
+import { createNodeLabel } from '../lib/reactivity/text/createNodeLabel.ts';
+import type { SimpleAtomicState } from '../lib/reactivity/types.ts';
+import type { ValueNodeDefinition } from '../model/ValueNodeDefinition.ts';
+import type { Root } from './Root.ts';
+import type { DescendantNodeStateSpec } from './abstract/DescendantNode.ts';
+import { DescendantNode } from './abstract/DescendantNode.ts';
+import type { GeneralParentNode } from './hierarchy.ts';
+import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
+import type { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
+import type { ValueContext } from './internal-api/ValueContext.ts';
+
+export interface StringFieldDefinition extends ValueNodeDefinition {
+	readonly bodyElement: InputDefinition | null;
+}
+
+interface StringFieldStateSpec extends DescendantNodeStateSpec<string> {
+	readonly label: Accessor<TextRange<'label'> | null>;
+	readonly hint: Accessor<TextRange<'hint'> | null>;
+	readonly children: null;
+	readonly value: SimpleAtomicState<string>;
+	readonly valueOptions: null;
+}
+
+export class StringField
+	extends DescendantNode<StringFieldDefinition, StringFieldStateSpec, null>
+	implements StringNode, EvaluationContext, SubscribableDependency, ValueContext<string>
+{
+	protected readonly state: SharedNodeState<StringFieldStateSpec>;
+
+	// InstanceNode
+	protected engineState: EngineState<StringFieldStateSpec>;
+
+	// StringNode
+	readonly nodeType = 'string';
+
+	readonly currentState: CurrentState<StringFieldStateSpec>;
+
+	// ValueContext
+	readonly encodeValue = identity<string>;
+
+	readonly decodeValue = identity<string>;
+
+	constructor(parent: GeneralParentNode, definition: StringFieldDefinition) {
+		super(parent, definition);
+
+		const state = createSharedNodeState(
+			this.scope,
+			{
+				...this.buildSharedStateSpec(parent, definition),
+
+				label: createNodeLabel(this, definition),
+				hint: createFieldHint(this, definition),
+				children: null,
+				valueOptions: null,
+				value: createValueState(this),
+			},
+			{
+				clientStateFactory: this.engineConfig.stateFactory,
+			}
+		);
+
+		this.state = state;
+		this.engineState = state.engineState;
+		this.currentState = state.currentState;
+	}
+
+	protected computeReference(parent: GeneralParentNode): string {
+		return this.computeChildStepReference(parent);
+	}
+
+	// InstanceNode
+	getChildren(): readonly [] {
+		return [];
+	}
+
+	// StringNode
+	setValue(value: string): Root {
+		this.state.setProperty('value', value);
+
+		return this.root;
+	}
+}

package/src/instance/Subtree.ts

@@ -0,0 +1,79 @@
+import { type Accessor } from 'solid-js';
+import type { SubtreeDefinition, SubtreeNode } from '../client/SubtreeNode.ts';
+import type { ChildrenState } from '../lib/reactivity/createChildrenState.ts';
+import { createChildrenState } from '../lib/reactivity/createChildrenState.ts';
+import type { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
+import { materializeCurrentStateChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
+import type { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
+import type { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
+import type { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
+import { createSharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
+import type { DescendantNodeSharedStateSpec } from './abstract/DescendantNode.ts';
+import { DescendantNode } from './abstract/DescendantNode.ts';
+import { buildChildren } from './children.ts';
+import type { GeneralChildNode, GeneralParentNode } from './hierarchy.ts';
+import type { NodeID } from './identity.ts';
+import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
+import type { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
+
+interface SubtreeStateSpec extends DescendantNodeSharedStateSpec {
+	readonly label: null;
+	readonly hint: null;
+	readonly children: Accessor<readonly NodeID[]>;
+	readonly valueOptions: null;
+	readonly value: null;
+}
+
+export class Subtree
+	extends DescendantNode<SubtreeDefinition, SubtreeStateSpec, GeneralChildNode>
+	implements SubtreeNode, EvaluationContext, SubscribableDependency
+{
+	private readonly childrenState: ChildrenState<GeneralChildNode>;
+
+	// InstanceNode
+	protected readonly state: SharedNodeState<SubtreeStateSpec>;
+	protected engineState: EngineState<SubtreeStateSpec>;
+
+	// SubtreeNode
+	readonly nodeType = 'subtree';
+
+	readonly currentState: MaterializedChildren<CurrentState<SubtreeStateSpec>, GeneralChildNode>;
+
+	constructor(parent: GeneralParentNode, definition: SubtreeDefinition) {
+		super(parent, definition);
+
+		const childrenState = createChildrenState<Subtree, GeneralChildNode>(this);
+
+		this.childrenState = childrenState;
+
+		const state = createSharedNodeState(
+			this.scope,
+			{
+				...this.buildSharedStateSpec(parent, definition),
+
+				label: null,
+				hint: null,
+				children: childrenState.childIds,
+				valueOptions: null,
+				value: null,
+			},
+			{
+				clientStateFactory: this.engineConfig.stateFactory,
+			}
+		);
+
+		this.state = state;
+		this.engineState = state.engineState;
+		this.currentState = materializeCurrentStateChildren(state.currentState, childrenState);
+
+		childrenState.setChildren(buildChildren(this));
+	}
+
+	protected computeReference(parent: GeneralParentNode): string {
+		return this.computeChildStepReference(parent);
+	}
+
+	getChildren(): readonly GeneralChildNode[] {
+		return this.childrenState.getChildren();
+	}
+}