@getodk/xforms-engine 0.1.1 → 0.2.0

package/src/instance/Root.ts

@@ -2,6 +2,7 @@ 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 { BodyClassList } from '../body/BodyDefinition.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';
@@ -98,27 +99,20 @@ export class Root
 		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
+	readonly hasReadonlyAncestor = () => false;
+	readonly isReadonly = () => false;
+	readonly hasNonRelevantAncestor = () => false;
+	readonly isRelevant = () => true;
 	protected readonly state: SharedNodeState<RootStateSpec>;
 	protected readonly engineState: EngineState<RootStateSpec>;
 
 	// RootNode
 	readonly nodeType = 'root';
-
+	readonly appearances = null;
+	readonly classes: BodyClassList;
 	readonly currentState: MaterializedChildren<CurrentState<RootStateSpec>, GeneralChildNode>;
 
 	protected readonly instanceDOM: XFormDOM;
@@ -129,12 +123,6 @@ export class Root
 	// EvaluationContext
 	readonly evaluator: XFormsXPathEvaluator;
 
-	private readonly rootReference: string;
-
-	override get contextReference(): string {
-		return this.rootReference;
-	}
-
 	readonly contextNode: Element;
 
 	// RootNode
@@ -147,20 +135,18 @@ export class Root
 		return this.engineState.activeLanguage;
 	}
 
-	protected constructor(
-		xformDOM: XFormDOM,
-		definition: RootDefinition,
-		engineConfig: InstanceConfig
-	) {
-		super(engineConfig, null, definition);
+	constructor(xformDOM: XFormDOM, definition: RootDefinition, engineConfig: InstanceConfig) {
+		const reference = definition.nodeset;
 
-		const childrenState = createChildrenState<Root, GeneralChildNode>(this);
+		super(engineConfig, null, definition, {
+			computeReference: () => reference,
+		});
 
-		this.childrenState = childrenState;
+		this.classes = definition.classes;
 
-		const reference = definition.nodeset;
+		const childrenState = createChildrenState<Root, GeneralChildNode>(this);
 
-		this.rootReference = reference;
+		this.childrenState = childrenState;
 
 		const instanceDOM = xformDOM.createInstance();
 		const evaluator = instanceDOM.primaryInstanceEvaluator;
@@ -187,7 +173,11 @@ export class Root
 
 		this.state = state;
 		this.engineState = state.engineState;
-		this.currentState = materializeCurrentStateChildren(state.currentState, childrenState);
+		this.currentState = materializeCurrentStateChildren(
+			this.scope,
+			state.currentState,
+			childrenState
+		);
 
 		const contextNode = instanceDOM.xformDocument.createElement(definition.nodeName);
 
@@ -201,40 +191,6 @@ export class Root
 		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();
 	}

package/src/instance/SelectField.ts

@@ -2,7 +2,7 @@ import { xmlXPathWhitespaceSeparatedList } from '@getodk/common/lib/string/white
 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 { SelectItem, SelectNode, SelectNodeAppearances } from '../client/SelectNode.ts';
 import type { TextRange } from '../index.ts';
 import { createSelectItems } from '../lib/reactivity/createSelectItems.ts';
 import { createValueState } from '../lib/reactivity/createValueState.ts';
@@ -50,7 +50,7 @@ export class SelectField
 
 	// SelectNode
 	readonly nodeType = 'select';
-
+	readonly appearances: SelectNodeAppearances;
 	readonly currentState: CurrentState<SelectFieldStateSpec>;
 
 	// ValueContext
@@ -83,6 +83,7 @@ export class SelectField
 	constructor(parent: GeneralParentNode, definition: SelectFieldDefinition) {
 		super(parent, definition);
 
+		this.appearances = definition.bodyElement.appearances;
 		this.selectExclusive = definition.bodyElement.type === 'select1';
 
 		const valueOptions = createSelectItems(this);
@@ -92,7 +93,10 @@ export class SelectField
 		const state = createSharedNodeState(
 			this.scope,
 			{
-				...this.buildSharedStateSpec(parent, definition),
+				reference: this.contextReference,
+				readonly: this.isReadonly,
+				relevant: this.isRelevant,
+				required: this.isRequired,
 
 				label: createNodeLabel(this, definition),
 				hint: createFieldHint(this, definition),
@@ -120,10 +124,6 @@ export class SelectField
 		);
 	}
 
-	protected computeReference(parent: GeneralParentNode): string {
-		return this.computeChildStepReference(parent);
-	}
-
 	protected updateSelectedItemValues(values: readonly string[]) {
 		const itemsByValue = untrack(() => this.getSelectItemsByValue());
 

package/src/instance/StringField.ts

@@ -1,7 +1,7 @@
 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 { StringNode, StringNodeAppearances } 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';
@@ -43,7 +43,7 @@ export class StringField
 
 	// StringNode
 	readonly nodeType = 'string';
-
+	readonly appearances: StringNodeAppearances;
 	readonly currentState: CurrentState<StringFieldStateSpec>;
 
 	// ValueContext
@@ -54,10 +54,15 @@ export class StringField
 	constructor(parent: GeneralParentNode, definition: StringFieldDefinition) {
 		super(parent, definition);
 
+		this.appearances = (definition.bodyElement?.appearances ?? null) as StringNodeAppearances;
+
 		const state = createSharedNodeState(
 			this.scope,
 			{
-				...this.buildSharedStateSpec(parent, definition),
+				reference: this.contextReference,
+				readonly: this.isReadonly,
+				relevant: this.isRelevant,
+				required: this.isRequired,
 
 				label: createNodeLabel(this, definition),
 				hint: createFieldHint(this, definition),
@@ -75,10 +80,6 @@ export class StringField
 		this.currentState = state.currentState;
 	}
 
-	protected computeReference(parent: GeneralParentNode): string {
-		return this.computeChildStepReference(parent);
-	}
-
 	// InstanceNode
 	getChildren(): readonly [] {
 		return [];

package/src/instance/Subtree.ts

@@ -36,7 +36,7 @@ export class Subtree
 
 	// SubtreeNode
 	readonly nodeType = 'subtree';
-
+	readonly appearances = null;
 	readonly currentState: MaterializedChildren<CurrentState<SubtreeStateSpec>, GeneralChildNode>;
 
 	constructor(parent: GeneralParentNode, definition: SubtreeDefinition) {
@@ -49,7 +49,10 @@ export class Subtree
 		const state = createSharedNodeState(
 			this.scope,
 			{
-				...this.buildSharedStateSpec(parent, definition),
+				reference: this.contextReference,
+				readonly: this.isReadonly,
+				relevant: this.isRelevant,
+				required: this.isRequired,
 
 				label: null,
 				hint: null,
@@ -64,15 +67,15 @@ export class Subtree
 
 		this.state = state;
 		this.engineState = state.engineState;
-		this.currentState = materializeCurrentStateChildren(state.currentState, childrenState);
+		this.currentState = materializeCurrentStateChildren(
+			this.scope,
+			state.currentState,
+			childrenState
+		);
 
 		childrenState.setChildren(buildChildren(this));
 	}
 
-	protected computeReference(parent: GeneralParentNode): string {
-		return this.computeChildStepReference(parent);
-	}
-
 	getChildren(): readonly GeneralChildNode[] {
 		return this.childrenState.getChildren();
 	}

package/src/instance/abstract/DescendantNode.ts

@@ -1,6 +1,5 @@
 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';
@@ -52,6 +51,10 @@ export type AnyDescendantNode = DescendantNode<
 	any
 >;
 
+interface DescendantNodeOptions {
+	readonly computeReference?: Accessor<string>;
+}
+
 export abstract class DescendantNode<
 		Definition extends DescendantNodeDefinition,
 		// eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -61,63 +64,62 @@ export abstract class DescendantNode<
 	extends InstanceNode<Definition, Spec, Child>
 	implements BaseNode, EvaluationContext, SubscribableDependency
 {
+	readonly hasReadonlyAncestor: Accessor<boolean> = () => {
+		const { parent } = this;
+
+		return parent.hasReadonlyAncestor() || parent.isReadonly();
+	};
+
+	readonly isSelfReadonly: Accessor<boolean>;
+
+	readonly isReadonly: Accessor<boolean> = () => {
+		if (this.hasReadonlyAncestor()) {
+			return true;
+		}
+
+		return this.isSelfReadonly();
+	};
+
+	readonly hasNonRelevantAncestor: Accessor<boolean> = () => {
+		const { parent } = this;
+
+		return parent.hasNonRelevantAncestor() || !parent.isRelevant();
+	};
+
+	readonly isSelfRelevant: Accessor<boolean>;
+
+	readonly isRelevant: Accessor<boolean> = () => {
+		if (this.hasNonRelevantAncestor()) {
+			return false;
+		}
+
+		return this.isSelfRelevant();
+	};
+
+	protected readonly isRequired: Accessor<boolean>;
+
 	readonly root: Root;
 	readonly evaluator: XFormsXPathEvaluator;
 	readonly contextNode: Element;
 
 	constructor(
 		override readonly parent: DescendantNodeParent<Definition>,
-		override readonly definition: Definition
+		override readonly definition: Definition,
+		options?: DescendantNodeOptions
 	) {
-		super(parent.engineConfig, parent, definition);
+		super(parent.engineConfig, parent, definition, options);
 
 		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();
-			});
+		const { readonly, relevant, required } = definition.bind;
 
-			// 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,
-			};
-		});
+		this.isSelfReadonly = createComputedExpression(this, readonly);
+		this.isSelfRelevant = createComputedExpression(this, relevant);
+		this.isRequired = createComputedExpression(this, required);
 	}
 
 	protected createContextNode(parentContextNode: Element, nodeName: string): Element {

package/src/instance/abstract/InstanceNode.ts

@@ -1,7 +1,7 @@
 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 { NodeAppearances } from '../../client/NodeAppearances.ts';
 import type { InstanceNodeType } from '../../client/node-types.ts';
 import type { TextRange } from '../../index.ts';
 import type { MaterializedChildren } from '../../lib/reactivity/materializeCurrentStateChildren.ts';
@@ -40,10 +40,6 @@ type AnyInstanceNode = InstanceNode<
 	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.
@@ -61,6 +57,21 @@ export type InstanceNodeCurrentState<
 				: null;
 		};
 
+interface ComputableReferenceNode {
+	readonly parent: AnyParentNode | null;
+	readonly definition: AnyNodeDefinition;
+}
+
+type ComputeInstanceNodeReference = <This extends ComputableReferenceNode>(
+	this: This,
+	parent: This['parent'],
+	definition: This['definition']
+) => string;
+
+export interface InstanceNodeOptions {
+	readonly computeReference?: () => string;
+}
+
 export abstract class InstanceNode<
 		Definition extends AnyNodeDefinition,
 		// eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -69,60 +80,32 @@ export abstract class InstanceNode<
 	>
 	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.
+	 * @package Exposed on every node type to facilitate inheritance, as well as
+	 * conditional behavior for value nodes.
 	 */
-	protected getInitializedState<K extends keyof EngineState<Spec>>(
-		key: K,
-		options: InitializedStateOptions<EngineState<Spec>, K>
-	): EngineState<Spec>[K] {
-		if (this.isStateInitialized()) {
-			return this.engineState[key];
-		}
+	abstract readonly hasReadonlyAncestor: Accessor<boolean>;
 
-		return options.uninitializedFallback;
-	}
+	/**
+	 * @package Exposed on every node type to facilitate inheritance, as well as
+	 * conditional behavior for value nodes.
+	 */
+	abstract readonly isReadonly: Accessor<boolean>;
 
 	/**
 	 * @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,
-		});
-	}
+	abstract readonly hasNonRelevantAncestor: Accessor<boolean>;
 
 	/**
 	 * @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,
-		});
-	}
+	abstract readonly isRelevant: Accessor<boolean>;
 
 	// BaseNode: identity
 	readonly nodeId: NodeID;
@@ -130,6 +113,8 @@ export abstract class InstanceNode<
 	// BaseNode: node types and variants (e.g. for narrowing)
 	abstract readonly nodeType: InstanceNodeType;
 
+	abstract readonly appearances: NodeAppearances<Definition>;
+
 	abstract readonly currentState: InstanceNodeCurrentState<Spec, Child>;
 
 	// BaseNode: structural
@@ -141,35 +126,40 @@ export abstract class InstanceNode<
 	// EvaluationContext *and* Subscribable: node-specific
 	readonly scope: ReactiveScope;
 
+	readonly computeReference: ComputeInstanceNodeReference;
+
+	protected readonly computeChildStepReference: ComputeInstanceNodeReference = (
+		parent,
+		definition
+	): string => {
+		if (parent == null) {
+			throw new Error(
+				'Cannot compute child step reference of node without parent (was this called from `Root`?)'
+			);
+		}
+
+		return `${parent.contextReference()}/${definition.nodeName}`;
+	};
+
 	// EvaluationContext: node-specific
-	get contextReference(): string {
+	readonly contextReference = (): string => {
 		return this.computeReference(this.parent, this.definition);
-	}
+	};
 
 	abstract readonly contextNode: Element;
 
 	constructor(
 		readonly engineConfig: InstanceConfig,
 		readonly parent: AnyParentNode | null,
-		readonly definition: Definition
+		readonly definition: Definition,
+		options?: InstanceNodeOptions
 	) {
+		this.computeReference = options?.computeReference ?? this.computeChildStepReference;
+
 		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');
-			}
-		});
 	}
 
 	/**
@@ -184,18 +174,13 @@ export abstract class InstanceNode<
 	 */
 	abstract getChildren(this: AnyInstanceNode): readonly AnyChildNode[];
 
-	protected abstract computeReference(
-		parent: AnyInstanceNode | null,
-		definition: Definition
-	): string;
-
-	getNodeByReference(
+	getNodesByReference(
 		this: AnyNode,
 		visited: WeakSet<AnyNode>,
 		dependencyReference: string
-	): SubscribableDependency | null {
+	): readonly SubscribableDependency[] {
 		if (visited.has(this)) {
-			return null;
+			return [];
 		}
 
 		visited.add(this);
@@ -203,39 +188,37 @@ export abstract class InstanceNode<
 		const { nodeset } = this.definition;
 
 		if (dependencyReference === nodeset) {
-			return this;
+			if (this.nodeType === 'repeat-instance') {
+				return [this.parent];
+			}
+
+			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.getChildren().flatMap((child) => {
+				return child.getNodesByReference(visited, dependencyReference);
+			});
 		}
 
-		return this.parent?.getNodeByReference(visited, dependencyReference) ?? null;
+		return this.parent?.getNodesByReference(visited, dependencyReference) ?? [];
 	}
 
 	// EvaluationContext: node-relative
-	getSubscribableDependencyByReference(
+	getSubscribableDependenciesByReference(
 		this: AnyNode,
 		reference: string
-	): SubscribableDependency | null {
-		const visited = new WeakSet<SubscribableDependency>();
+	): readonly SubscribableDependency[] {
+		if (this.nodeType === 'root') {
+			const visited = new WeakSet<AnyNode>();
+
+			return this.getNodesByReference(visited, reference);
+		}
 
-		return this.getNodeByReference(visited, reference);
+		return this.root.getSubscribableDependenciesByReference(reference);
 	}
 
 	// SubscribableDependency