@getodk/xforms-engine 0.1.0

package/src/instance/abstract/DescendantNode.ts

@@ -0,0 +1,182 @@
+import type { XFormsXPathEvaluator } from '@getodk/xpath';
+import type { Accessor } from 'solid-js';
+import { createMemo } from 'solid-js';
+import type { BaseNode } from '../../client/BaseNode.ts';
+import { createComputedExpression } from '../../lib/reactivity/createComputedExpression.ts';
+import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
+import type { AnyDescendantNodeDefinition } from '../../model/DescendentNodeDefinition.ts';
+import type { AnyNodeDefinition } from '../../model/NodeDefinition.ts';
+import type { RepeatInstanceDefinition } from '../../model/RepeatInstanceDefinition.ts';
+import type { ValueNodeDefinition } from '../../model/ValueNodeDefinition.ts';
+import type { RepeatInstance } from '../RepeatInstance.ts';
+import type { RepeatRange } from '../RepeatRange.ts';
+import type { Root } from '../Root.ts';
+import type { AnyChildNode, GeneralParentNode } from '../hierarchy.ts';
+import type { EvaluationContext } from '../internal-api/EvaluationContext.ts';
+import type { SubscribableDependency } from '../internal-api/SubscribableDependency.ts';
+import type { InstanceNodeStateSpec } from './InstanceNode.ts';
+import { InstanceNode } from './InstanceNode.ts';
+
+export interface DescendantNodeSharedStateSpec {
+	readonly reference: Accessor<string>;
+	readonly readonly: Accessor<boolean>;
+	readonly relevant: Accessor<boolean>;
+	readonly required: Accessor<boolean>;
+}
+
+// prettier-ignore
+export type DescendantNodeStateSpec<Value = never> =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	& InstanceNodeStateSpec<Value>
+	& DescendantNodeSharedStateSpec;
+
+// prettier-ignore
+export type DescendantNodeDefinition = Extract<
+	AnyNodeDefinition,
+	AnyDescendantNodeDefinition
+>;
+
+// prettier-ignore
+export type DescendantNodeParent<Definition extends DescendantNodeDefinition> =
+	Definition extends ValueNodeDefinition
+		? GeneralParentNode
+	: Definition extends RepeatInstanceDefinition
+		? RepeatRange
+		: GeneralParentNode;
+
+export type AnyDescendantNode = DescendantNode<
+	DescendantNodeDefinition,
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	DescendantNodeStateSpec<any>,
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	any
+>;
+
+export abstract class DescendantNode<
+		Definition extends DescendantNodeDefinition,
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		Spec extends DescendantNodeStateSpec<any>,
+		Child extends AnyChildNode | null = null,
+	>
+	extends InstanceNode<Definition, Spec, Child>
+	implements BaseNode, EvaluationContext, SubscribableDependency
+{
+	readonly root: Root;
+	readonly evaluator: XFormsXPathEvaluator;
+	readonly contextNode: Element;
+
+	constructor(
+		override readonly parent: DescendantNodeParent<Definition>,
+		override readonly definition: Definition
+	) {
+		super(parent.engineConfig, parent, definition);
+
+		const { evaluator, root } = parent;
+
+		this.root = root;
+		this.evaluator = evaluator;
+		this.contextNode = this.initializeContextNode(parent.contextNode, definition.nodeName);
+	}
+
+	protected computeChildStepReference(parent: DescendantNodeParent<Definition>): string {
+		return `${parent.contextReference}/${this.definition.nodeName}`;
+	}
+
+	protected abstract override computeReference(
+		parent: DescendantNodeParent<Definition>,
+		definition: Definition
+	): string;
+
+	protected buildSharedStateSpec(
+		parent: DescendantNodeParent<Definition>,
+		definition: Definition
+	): DescendantNodeSharedStateSpec {
+		return this.scope.runTask(() => {
+			const reference = createMemo(() => this.contextReference);
+			const { bind } = definition;
+
+			// TODO: we can likely short-circuit `readonly` computation when a node
+			// is non-relevant.
+			const selfReadonly = createComputedExpression(this, bind.readonly);
+			const readonly = createMemo(() => {
+				return parent.isReadonly || selfReadonly();
+			});
+
+			const selfRelevant = createComputedExpression(this, bind.relevant);
+			const relevant = createMemo(() => {
+				return parent.isRelevant && selfRelevant();
+			});
+
+			// TODO: we can likely short-circuit `required` computation when a node
+			// is non-relevant.
+			const required = createComputedExpression(this, bind.required);
+
+			return {
+				reference,
+				readonly,
+				relevant,
+				required,
+			};
+		});
+	}
+
+	protected createContextNode(parentContextNode: Element, nodeName: string): Element {
+		return parentContextNode.ownerDocument.createElement(nodeName);
+	}
+
+	/**
+	 * Currently expected to be overridden by...
+	 *
+	 * - Repeat range: returns its parent's context node, because it doesn't have
+	 *   a node in the primary instance tree.
+	 *
+	 * - Repeat instance: returns its created context node, but overrides handles
+	 *   appending behavior separately (for inserting at the end of its parent
+	 *   range, or even at an arbitrary index within the range, after instance
+	 *   creation is has completed).
+	 */
+	protected initializeContextNode(parentContextNode: Element, nodeName: string): Element {
+		const element = this.createContextNode(parentContextNode, nodeName);
+
+		parentContextNode.append(element);
+
+		return element;
+	}
+
+	/**
+	 * @package
+	 *
+	 * Performs recursive removal, first of the node's descendants, then of the
+	 * node itself. For all {@link DescendantNode}s, removal involves **at least**
+	 * disposal of its {@link scope} ({@link ReactiveScope}).
+	 *
+	 * It is expected that the outermost node targeted for removal will always be
+	 * a {@link RepeatInstance}. @see {@link RepeatInstance.remove} for additional
+	 * details.
+	 *
+	 * It is also expected that upon that outermost node's removal, its parent
+	 * {@link RepeatRange} will perform a reactive update to its children state so
+	 * that:
+	 *
+	 * 1. Any downstream computations affected by the removal are updated.
+	 * 2. The client invoking removal is also reactively updated (where
+	 *    applicable).
+	 *
+	 * @see {@link RepeatInstance.remove} and {@link RepeatRange.removeInstances}
+	 * for additional details about their respective node-specific removal
+	 * behaviors and ordering.
+	 *
+	 * @todo Possibly retain removed repeat instances in memory. This came up as a
+	 * behavior of Collect/JavaRosa, and we should investigate the details and
+	 * ramifications of that, and whether it's the desired behavior.
+	 */
+	remove(this: AnyChildNode): void {
+		this.scope.runTask(() => {
+			this.getChildren().forEach((child) => {
+				child.remove();
+			});
+		});
+
+		this.scope.dispose();
+	}
+}

package/src/instance/abstract/InstanceNode.ts

@@ -0,0 +1,257 @@
+import type { XFormsXPathEvaluator } from '@getodk/xpath';
+import type { Accessor, Signal } from 'solid-js';
+import { createSignal } from 'solid-js';
+import type { BaseNode } from '../../client/BaseNode.ts';
+import type { InstanceNodeType } from '../../client/node-types.ts';
+import type { TextRange } from '../../index.ts';
+import type { MaterializedChildren } 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 type { ReactiveScope } from '../../lib/reactivity/scope.ts';
+import { createReactiveScope } from '../../lib/reactivity/scope.ts';
+import type { SimpleAtomicState } from '../../lib/reactivity/types.ts';
+import type { AnyNodeDefinition } from '../../model/NodeDefinition.ts';
+import type { Root } from '../Root.ts';
+import type { AnyChildNode, AnyNode, AnyParentNode } from '../hierarchy.ts';
+import type { NodeID } from '../identity.ts';
+import { declareNodeID } from '../identity.ts';
+import type { EvaluationContext } from '../internal-api/EvaluationContext.ts';
+import type { InstanceConfig } from '../internal-api/InstanceConfig.ts';
+import type { SubscribableDependency } from '../internal-api/SubscribableDependency.ts';
+
+export interface InstanceNodeStateSpec<Value = never> {
+	readonly reference: Accessor<string> | string;
+	readonly readonly: Accessor<boolean> | boolean;
+	readonly relevant: Accessor<boolean> | boolean;
+	readonly required: Accessor<boolean> | boolean;
+	readonly label: Accessor<TextRange<'label'> | null> | null;
+	readonly hint: Accessor<TextRange<'hint'> | null> | null;
+	readonly children: Accessor<readonly NodeID[]> | null;
+	readonly valueOptions: Accessor<null> | Accessor<readonly unknown[]> | null;
+	readonly value: Signal<Value> | SimpleAtomicState<Value> | null;
+}
+
+type AnyInstanceNode = InstanceNode<
+	AnyNodeDefinition,
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	InstanceNodeStateSpec<any>,
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	any
+>;
+
+interface InitializedStateOptions<T, K extends keyof T> {
+	readonly uninitializedFallback: T[K];
+}
+
+/**
+ * This type has the same effect as {@link MaterializedChildren}, but abstractly
+ * handles leaf node types as well.
+ */
+// prettier-ignore
+export type InstanceNodeCurrentState<
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	Spec extends InstanceNodeStateSpec<any>,
+	Child
+> =
+	& CurrentState<Omit<Spec, 'children'>>
+	& {
+			readonly children: [Child] extends [AnyChildNode]
+				? readonly Child[]
+				: null;
+		};
+
+export abstract class InstanceNode<
+		Definition extends AnyNodeDefinition,
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		Spec extends InstanceNodeStateSpec<any>,
+		Child extends AnyChildNode | null = null,
+	>
+	implements BaseNode, EvaluationContext, SubscribableDependency
+{
+	protected readonly isStateInitialized: Accessor<boolean>;
+
+	protected abstract readonly state: SharedNodeState<Spec>;
+	protected abstract readonly engineState: EngineState<Spec>;
+
+	/**
+	 * Provides a generalized mechanism for accessing a reactive state value
+	 * during a node's construction, while {@link engineState} is still being
+	 * defined and thus isn't assigned.
+	 *
+	 * The fallback value specified in {@link options} will be returned on access
+	 * until {@link isStateInitialized} returns true. This ensures:
+	 *
+	 * - a value of the expected type will be available
+	 * - any read access will become reactive to the actual state, once it has
+	 *   been initialized and {@link engineState} is assigned
+	 *
+	 * @todo This is one among several chicken/egg problems encountered trying to
+	 * support state initialization in which some aspects of the state derive from
+	 * other aspects of it. It would be nice to dispense with this entirely. But
+	 * if it must persist, we should also consider replacing the method with a
+	 * direct accessor once state initialization completes, so the initialized
+	 * check is only called until it becomes impertinent.
+	 */
+	protected getInitializedState<K extends keyof EngineState<Spec>>(
+		key: K,
+		options: InitializedStateOptions<EngineState<Spec>, K>
+	): EngineState<Spec>[K] {
+		if (this.isStateInitialized()) {
+			return this.engineState[key];
+		}
+
+		return options.uninitializedFallback;
+	}
+
+	/**
+	 * @package Exposed on every node type to facilitate inheritance, as well as
+	 * conditional behavior for value nodes.
+	 */
+	get isReadonly(): boolean {
+		return (this as AnyInstanceNode).getInitializedState('readonly', {
+			uninitializedFallback: false,
+		});
+	}
+
+	/**
+	 * @package Exposed on every node type to facilitate inheritance, as well as
+	 * conditional behavior for value nodes.
+	 */
+	get isRelevant(): boolean {
+		return (this as AnyInstanceNode).getInitializedState('relevant', {
+			uninitializedFallback: true,
+		});
+	}
+
+	// BaseNode: identity
+	readonly nodeId: NodeID;
+
+	// BaseNode: node types and variants (e.g. for narrowing)
+	abstract readonly nodeType: InstanceNodeType;
+
+	abstract readonly currentState: InstanceNodeCurrentState<Spec, Child>;
+
+	// BaseNode: structural
+	abstract readonly root: Root;
+
+	// EvaluationContext: instance-global/shared
+	abstract readonly evaluator: XFormsXPathEvaluator;
+
+	// EvaluationContext *and* Subscribable: node-specific
+	readonly scope: ReactiveScope;
+
+	// EvaluationContext: node-specific
+	get contextReference(): string {
+		return this.computeReference(this.parent, this.definition);
+	}
+
+	abstract readonly contextNode: Element;
+
+	constructor(
+		readonly engineConfig: InstanceConfig,
+		readonly parent: AnyParentNode | null,
+		readonly definition: Definition
+	) {
+		this.scope = createReactiveScope();
+		this.engineConfig = engineConfig;
+		this.nodeId = declareNodeID(engineConfig.createUniqueId());
+		this.definition = definition;
+
+		const checkStateInitialized = () => this.engineState != null;
+		const [isStateInitialized, setStateInitialized] = createSignal(checkStateInitialized());
+
+		this.isStateInitialized = isStateInitialized;
+
+		queueMicrotask(() => {
+			if (checkStateInitialized()) {
+				setStateInitialized(true);
+			} else {
+				throw new Error('Node state was never initialized');
+			}
+		});
+	}
+
+	/**
+	 * @package This presently serves a few internal use cases, where certain
+	 * behaviors depend on arbitrary traversal from any point in the instance
+	 * tree, without particular regard for the visited node type. It isn't
+	 * intended for external traversal or any other means of consuming children by
+	 * a client. This return type intentionally deviates from one structural
+	 * expectation, requiring even leaf nodes to return an array (though for those
+	 * nodes it will always be empty). This affords consistency and efficiency of
+	 * interface for those internal uses.
+	 */
+	abstract getChildren(this: AnyInstanceNode): readonly AnyChildNode[];
+
+	protected abstract computeReference(
+		parent: AnyInstanceNode | null,
+		definition: Definition
+	): string;
+
+	getNodeByReference(
+		this: AnyNode,
+		visited: WeakSet<AnyNode>,
+		dependencyReference: string
+	): SubscribableDependency | null {
+		if (visited.has(this)) {
+			return null;
+		}
+
+		visited.add(this);
+
+		const { nodeset } = this.definition;
+
+		if (dependencyReference === nodeset) {
+			return this;
+		}
+
+		if (
+			dependencyReference.startsWith(`${nodeset}/`) ||
+			dependencyReference.startsWith(`${nodeset}[`)
+		) {
+			const children = this.getChildren();
+
+			if (children == null) {
+				return null;
+			}
+
+			for (const child of children) {
+				const dependency = child.getNodeByReference(visited, dependencyReference);
+
+				if (dependency != null) {
+					return dependency;
+				}
+			}
+		}
+
+		return this.parent?.getNodeByReference(visited, dependencyReference) ?? null;
+	}
+
+	// EvaluationContext: node-relative
+	getSubscribableDependencyByReference(
+		this: AnyNode,
+		reference: string
+	): SubscribableDependency | null {
+		const visited = new WeakSet<SubscribableDependency>();
+
+		return this.getNodeByReference(visited, reference);
+	}
+
+	// SubscribableDependency
+	/**
+	 * This is a default implementation suitable for most node types. The rest
+	 * (currently: `Root`, `RepeatRange`, `RepeatInstance`) should likely extend
+	 * this behavior, rather than simply overriding it.
+	 */
+	subscribe(): void {
+		const { engineState } = this;
+
+		if (engineState.relevant) {
+			engineState.reference;
+			engineState.relevant;
+			engineState.children;
+			engineState.value;
+		}
+	}
+}

package/src/instance/children.ts

@@ -0,0 +1,52 @@
+import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
+import { SelectDefinition } from '../body/control/select/SelectDefinition.ts';
+import type { GroupDefinition } from '../client/GroupNode.ts';
+import type { SubtreeDefinition } from '../client/SubtreeNode.ts';
+import type { SubtreeDefinition as ModelSubtreeDefinition } from '../model/SubtreeDefinition.ts';
+import { Group } from './Group.ts';
+import { RepeatRange } from './RepeatRange.ts';
+import { SelectField, type SelectFieldDefinition } from './SelectField.ts';
+import { StringField } from './StringField.ts';
+import { Subtree } from './Subtree.ts';
+import type { GeneralChildNode, GeneralParentNode } from './hierarchy.ts';
+
+const isSubtreeDefinition = (
+	definition: ModelSubtreeDefinition
+): definition is SubtreeDefinition => {
+	return definition.bodyElement == null;
+};
+
+export const buildChildren = (parent: GeneralParentNode): GeneralChildNode[] => {
+	const { children } = parent.definition;
+
+	return children.map((child): GeneralChildNode => {
+		switch (child.type) {
+			case 'subtree': {
+				if (isSubtreeDefinition(child)) {
+					return new Subtree(parent, child);
+				}
+
+				// TODO: it'd be good to be able to do without this type assertion. The
+				// only distinction between the types is whether `bodyElement` is
+				// `null`, but for some reason that's insufficient to narrow the union.
+				return new Group(parent, child as GroupDefinition);
+			}
+
+			case 'repeat-sequence': {
+				return new RepeatRange(parent, child);
+			}
+
+			case 'value-node': {
+				if (child.bodyElement instanceof SelectDefinition) {
+					return new SelectField(parent, child as SelectFieldDefinition);
+				}
+
+				return new StringField(parent, child);
+			}
+
+			default: {
+				throw new UnreachableError(child);
+			}
+		}
+	});
+};

package/src/instance/hierarchy.ts

@@ -0,0 +1,54 @@
+import type { Group } from './Group.ts';
+import type { RepeatInstance } from './RepeatInstance.ts';
+import type { RepeatRange } from './RepeatRange.ts';
+import type { Root } from './Root.ts';
+import type { SelectField } from './SelectField.ts';
+import type { StringField } from './StringField.ts';
+import type { Subtree } from './Subtree.ts';
+
+// prettier-ignore
+export type AnyNode =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| Root
+	| Group
+	| Subtree
+	| RepeatRange
+	| RepeatInstance
+	| StringField
+	| SelectField;
+
+// prettier-ignore
+export type AnyParentNode =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| Root
+	| Group
+	| Subtree
+	| RepeatRange
+	| RepeatInstance;
+
+// prettier-ignore
+export type GeneralParentNode =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| Root
+	| Group
+	| Subtree
+	| RepeatInstance;
+
+// prettier-ignore
+export type AnyChildNode =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| Group
+	| Subtree
+	| RepeatRange
+	| RepeatInstance
+	| StringField
+	| SelectField;
+
+// prettier-ignore
+export type GeneralChildNode =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| Group
+	| Subtree
+	| RepeatRange
+	| StringField
+	| SelectField;

package/src/instance/identity.ts

@@ -0,0 +1,11 @@
+declare const NODE_ID_BRAND: unique symbol;
+type NODE_ID_BRAND = typeof NODE_ID_BRAND;
+
+export type NodeID = string & { readonly [NODE_ID_BRAND]: true };
+
+// Just another added safeguard to ensure we're not mistakenly handling
+// rando `NodeID` strings which aren't explicitly attached to the node
+// types we expect.
+export const declareNodeID = (id: string): NodeID => {
+	return id as NodeID;
+};

package/src/instance/index.ts

@@ -0,0 +1,37 @@
+import { identity } from '@getodk/common/lib/identity.ts';
+import { XFormDefinition } from '../XFormDefinition.ts';
+import type { RootNode } from '../client/RootNode.ts';
+import type {
+	InitializeFormOptions as BaseInitializeFormOptions,
+	FormResource,
+	InitializeForm,
+} from '../client/index.ts';
+import { retrieveSourceXMLResource } from '../instance/resource.ts';
+import { createUniqueId } from '../lib/unique-id.ts';
+import { Root } from './Root.ts';
+import type { InstanceConfig } from './internal-api/InstanceConfig.ts';
+
+interface InitializeFormOptions extends BaseInitializeFormOptions {
+	readonly config: Partial<InstanceConfig>;
+}
+
+const buildInstanceConfig = (options: Partial<InstanceConfig> = {}): InstanceConfig => {
+	return {
+		createUniqueId: options.createUniqueId ?? createUniqueId,
+		fetchResource: options.fetchResource ?? fetch,
+		stateFactory: options.stateFactory ?? identity,
+	};
+};
+
+export const initializeForm = async (
+	input: FormResource,
+	options: Partial<InitializeFormOptions> = {}
+): Promise<RootNode> => {
+	const engineConfig = buildInstanceConfig(options.config);
+	const sourceXML = await retrieveSourceXMLResource(input, engineConfig);
+	const form = new XFormDefinition(sourceXML);
+
+	return Root.initialize(form.xformDOM, form.model.root, engineConfig);
+};
+
+initializeForm satisfies InitializeForm;

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

@@ -0,0 +1,41 @@
+import type { XFormsXPathEvaluator } from '@getodk/xpath';
+import type { DependentExpression } from '../../expression/DependentExpression.ts';
+import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
+import type { SubscribableDependency } from './SubscribableDependency.ts';
+import type { TranslationContext } from './TranslationContext.ts';
+
+export interface EvaluationContextRoot extends SubscribableDependency, TranslationContext {}
+
+/**
+ * Provides a common interface to establish context for XPath-based
+ * computations, i.e. to evaluate {@link DependentExpression}s where:
+ *
+ * - the expression may have dynamic dependency **references** (e.g. relative
+ *   references resolve to repeat instances or their descendants)
+ * - the expression may reference dynamic dependency **values** (e.g. an
+ *   expression referencing the value of another node)
+ * - the expression may be dependent on the form's currently active language
+ *   (e.g. `jr:itext`)
+ * - any dynamic case is expected to be internally reactive
+ */
+export interface EvaluationContext {
+	readonly scope: ReactiveScope;
+	readonly evaluator: XFormsXPathEvaluator;
+	readonly root: EvaluationContextRoot;
+
+	/**
+	 * Produces the current absolute reference to the {@link contextNode}, where
+	 * the absolute `/` resolves to the active form state's primary instance root.
+	 */
+	get contextReference(): string;
+
+	readonly contextNode: Node;
+
+	/**
+	 * Resolves a nodeset reference, possibly relative to the
+	 * {@link EvaluationContext.contextNode}.
+	 */
+	readonly getSubscribableDependencyByReference: (
+		reference: string
+	) => SubscribableDependency | null;
+}

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

@@ -0,0 +1,9 @@
+import type { EngineConfig } from '../../client/EngineConfig.ts';
+import type { CreateUniqueId } from '../../lib/unique-id.ts';
+
+export interface InstanceConfig extends Required<EngineConfig> {
+	/**
+	 * Uniqueness per form instance session (so e.g. persistence isn't necessary).
+	 */
+	readonly createUniqueId: CreateUniqueId;
+}