@getodk/xforms-engine 0.3.0 → 0.5.0

package/src/instance/PrimaryInstance.ts

@@ -0,0 +1,244 @@
+import { XPathNodeKindKey } from '@getodk/xpath';
+import type { Accessor } from 'solid-js';
+import { createSignal } from 'solid-js';
+import type { ActiveLanguage, FormLanguage, FormLanguages } from '../client/FormLanguage.ts';
+import type { FormNodeID } from '../client/identity.ts';
+import type { RootNode } from '../client/RootNode.ts';
+import type {
+	SubmissionChunkedType,
+	SubmissionOptions,
+} from '../client/submission/SubmissionOptions.ts';
+import type { SubmissionResult } from '../client/submission/SubmissionResult.ts';
+import type { SubmissionState } from '../client/submission/SubmissionState.ts';
+import type { AncestorNodeValidationState } from '../client/validation.ts';
+import type { XFormsXPathDocument } from '../integration/xpath/adapter/XFormsXPathNode.ts';
+import { EngineXPathEvaluator } from '../integration/xpath/EngineXPathEvaluator.ts';
+import { createInstanceSubmissionState } from '../lib/client-reactivity/submission/createInstanceSubmissionState.ts';
+import { prepareSubmission } from '../lib/client-reactivity/submission/prepareSubmission.ts';
+import { createChildrenState } from '../lib/reactivity/createChildrenState.ts';
+import { createTranslationState } from '../lib/reactivity/createTranslationState.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 { ReactiveScope } from '../lib/reactivity/scope.ts';
+import type { SimpleAtomicStateSetter } from '../lib/reactivity/types.ts';
+import type { BodyClassList } from '../parse/body/BodyDefinition.ts';
+import type { ModelDefinition } from '../parse/model/ModelDefinition.ts';
+import type { RootDefinition } from '../parse/model/RootDefinition.ts';
+import type { SecondaryInstancesDefinition } from '../parse/model/SecondaryInstance/SecondaryInstancesDefinition.ts';
+import { InstanceNode } from './abstract/InstanceNode.ts';
+import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
+import type { InstanceConfig } from './internal-api/InstanceConfig.ts';
+import type { PrimaryInstanceDocument } from './internal-api/PrimaryInstanceDocument.ts';
+import type { ClientReactiveSubmittableInstance } from './internal-api/submission/ClientReactiveSubmittableInstance.ts';
+import type { TranslationContext } from './internal-api/TranslationContext.ts';
+import { Root } from './Root.ts';
+
+/**
+ * As specified by {@link | XPath 1.0}:
+ *
+ * > A `/` by itself selects the root node of the document containing the
+ * > context node.
+ *
+ * Important note: "root node" here references the same semantics currently
+ * represented by `@getodk/xpath` as {@link XPathDocument}. It is an infortunate
+ * historical mistake that our internal representation of a primary instance has
+ * conflated the same "root" term to represent the "document element" with the
+ * same semantic name.
+ *
+ * {@link PrimaryInstance} exists specifically to provide XPath document
+ * semantics. At time of writing, it is expected that every XPath evaluation
+ * will be performed with a context node either:
+ *
+ * - somewhere in this primary instance document's hierarchy; or
+ * - in a related subtree where the primary instance document is still
+ *   semantically represented as the context root node
+ */
+const PRIMARY_INSTANCE_REFERENCE = '/';
+
+interface PrimaryInstanceStateSpec {
+	readonly reference: string;
+	readonly readonly: boolean;
+	readonly relevant: boolean;
+	readonly required: boolean;
+	readonly label: null;
+	readonly hint: null;
+	readonly children: Accessor<readonly FormNodeID[]>;
+	readonly valueOptions: null;
+	readonly value: null;
+
+	// Root-specific
+	readonly activeLanguage: Accessor<ActiveLanguage>;
+}
+
+export class PrimaryInstance
+	extends InstanceNode<RootDefinition, PrimaryInstanceStateSpec, null, Root>
+	implements
+		PrimaryInstanceDocument,
+		XFormsXPathDocument,
+		TranslationContext,
+		EvaluationContext,
+		ClientReactiveSubmittableInstance
+{
+	// InstanceNode
+	protected readonly state: SharedNodeState<PrimaryInstanceStateSpec>;
+	protected readonly engineState: EngineState<PrimaryInstanceStateSpec>;
+	readonly getChildren: Accessor<readonly Root[]>;
+
+	readonly hasReadonlyAncestor = () => false;
+	readonly isReadonly = () => false;
+	readonly hasNonRelevantAncestor = () => false;
+	readonly isRelevant = () => true;
+
+	// TranslationContext (support)
+	private readonly setActiveLanguage: SimpleAtomicStateSetter<FormLanguage>;
+
+	// XFormsXPathDocument
+	readonly [XPathNodeKindKey] = 'document';
+
+	// PrimaryInstanceDocument, ClientReactiveSubmittableInstance
+	readonly nodeType = 'primary-instance';
+	readonly appearances = null;
+	readonly classes: BodyClassList;
+	readonly root: Root;
+	readonly currentState: MaterializedChildren<CurrentState<PrimaryInstanceStateSpec>, Root>;
+	readonly validationState: AncestorNodeValidationState;
+	readonly submissionState: SubmissionState;
+	readonly languages: FormLanguages;
+
+	// TranslationContext (+ EvaluationContext)
+	readonly getActiveLanguage: Accessor<ActiveLanguage>;
+
+	// EvaluationContext
+	readonly isAttached: Accessor<boolean>;
+	readonly evaluator: EngineXPathEvaluator;
+	override readonly contextNode = this;
+
+	constructor(
+		scope: ReactiveScope,
+		model: ModelDefinition,
+		secondaryInstances: SecondaryInstancesDefinition,
+		engineConfig: InstanceConfig
+	) {
+		const { root: definition } = model;
+
+		super(engineConfig, null, definition, {
+			scope,
+			computeReference: () => PRIMARY_INSTANCE_REFERENCE,
+		});
+
+		const [isAttached, setIsAttached] = createSignal(false);
+
+		this.isAttached = isAttached;
+
+		const evaluator = new EngineXPathEvaluator({
+			rootNode: this,
+			itextTranslationsByLanguage: model.itextTranslations,
+			secondaryInstancesById: secondaryInstances,
+		});
+
+		const { languages, getActiveLanguage, setActiveLanguage } = createTranslationState(
+			scope,
+			evaluator
+		);
+
+		this.languages = languages;
+		this.getActiveLanguage = getActiveLanguage;
+		this.setActiveLanguage = setActiveLanguage;
+
+		this.evaluator = evaluator;
+		this.classes = definition.classes;
+
+		const childrenState = createChildrenState<this, Root>(this);
+
+		this.getChildren = childrenState.getChildren;
+
+		const stateSpec: PrimaryInstanceStateSpec = {
+			activeLanguage: getActiveLanguage,
+			reference: PRIMARY_INSTANCE_REFERENCE,
+			label: null,
+			hint: null,
+			readonly: false,
+			relevant: true,
+			required: false,
+			valueOptions: null,
+			value: null,
+			children: childrenState.childIds,
+		};
+
+		const state = createSharedNodeState(scope, stateSpec, {
+			clientStateFactory: engineConfig.stateFactory,
+		});
+
+		this.state = state;
+		this.engineState = state.engineState;
+		this.currentState = materializeCurrentStateChildren(scope, state.currentState, childrenState);
+
+		const root = new Root(this);
+
+		this.root = root;
+
+		this.validationState = {
+			get violations() {
+				return root.validationState.violations;
+			},
+		};
+		this.submissionState = createInstanceSubmissionState(this);
+
+		childrenState.setChildren([root]);
+		setIsAttached(true);
+	}
+
+	// PrimaryInstanceDocument
+	/**
+	 * @todo Note that this method's signature is intentionally derived from
+	 * {@link RootNode.setLanguage}, but its return type differs! The design
+	 * intent of returning {@link RootNode} from all of the client-facing state
+	 * setter methods has proven… interesting philosophically. But nothing
+	 * downstream has availed itself of that philosophy, and otherwise it's not
+	 * particularly pragmatic or ergonomic (internally or for clients alike).
+	 *
+	 * Since this class is (currently) engine-internal, this seems like an
+	 * excellent place to start a discussion around what we want longer term for
+	 * state setter signatures in _client-facing_ APIs. As a first pass, it seems
+	 * reasonable to borrow the idiomatic convention of returning the effective
+	 * value assigned by the setter.
+	 *
+	 * @see
+	 * {@link https://github.com/getodk/web-forms/issues/45#issuecomment-1967932261 | Initial read interface design between engine and UI - design summary comment}
+	 * (and some of the comments leading up to it) for background on the
+	 * philosophical reasoning behind the existing signature convention.
+	 */
+	setLanguage(language: FormLanguage): FormLanguage {
+		const availableFormLanguage = this.languages.find(
+			(formLanguage): formLanguage is FormLanguage => {
+				return (
+					formLanguage.isSyntheticDefault == null && formLanguage.language === language.language
+				);
+			}
+		);
+
+		if (availableFormLanguage == null) {
+			throw new Error(`Language "${language.language}" not available`);
+		}
+
+		this.evaluator.setActiveLanguage(availableFormLanguage.language);
+
+		return this.setActiveLanguage(availableFormLanguage);
+	}
+
+	// PrimaryInstanceDocument, ClientReactiveSubmittableInstance
+	prepareSubmission<ChunkedType extends SubmissionChunkedType = 'monolithic'>(
+		options?: SubmissionOptions<ChunkedType>
+	): Promise<SubmissionResult<ChunkedType>> {
+		const result = prepareSubmission(this, {
+			chunked: (options?.chunked ?? 'monolithic') as ChunkedType,
+			maxSize: options?.maxSize ?? Infinity,
+		});
+
+		return Promise.resolve(result);
+	}
+}

package/src/instance/Root.ts

@@ -1,11 +1,18 @@
-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 { XPathNodeKindKey } from '@getodk/xpath';
+import type { Accessor } from 'solid-js';
 import type { ActiveLanguage, FormLanguage, FormLanguages } from '../client/FormLanguage.ts';
+import type { FormNodeID } from '../client/identity.ts';
 import type { RootNode } from '../client/RootNode.ts';
+import type { SubmissionDefinition } from '../client/submission/SubmissionDefinition.ts';
+import type {
+	SubmissionChunkedType,
+	SubmissionOptions,
+} from '../client/submission/SubmissionOptions.ts';
+import type { SubmissionResult } from '../client/submission/SubmissionResult.ts';
+import type { SubmissionState } from '../client/submission/SubmissionState.ts';
 import type { AncestorNodeValidationState } from '../client/validation.ts';
+import type { XFormsXPathElement } from '../integration/xpath/adapter/XFormsXPathNode.ts';
+import { createParentNodeSubmissionState } from '../lib/client-reactivity/submission/createParentNodeSubmissionState.ts';
 import type { ChildrenState } from '../lib/reactivity/createChildrenState.ts';
 import { createChildrenState } from '../lib/reactivity/createChildrenState.ts';
 import type { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
@@ -15,146 +22,89 @@ import type { EngineState } from '../lib/reactivity/node-state/createEngineState
 import type { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
 import { createSharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
 import { createAggregatedViolations } from '../lib/reactivity/validation/createAggregatedViolations.ts';
-import type { RootDefinition } from '../model/RootDefinition.ts';
-import { InstanceNode } from './abstract/InstanceNode.ts';
+import type { BodyClassList } from '../parse/body/BodyDefinition.ts';
+import type { RootDefinition } from '../parse/model/RootDefinition.ts';
+import { DescendantNode } from './abstract/DescendantNode.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 { EvaluationContext } from './internal-api/EvaluationContext.ts';
+import type { ClientReactiveSubmittableParentNode } from './internal-api/submission/ClientReactiveSubmittableParentNode.ts';
 import type { TranslationContext } from './internal-api/TranslationContext.ts';
+import type { PrimaryInstance } from './PrimaryInstance.ts';
 
 interface RootStateSpec {
-	readonly reference: string;
-	readonly readonly: boolean;
-	readonly relevant: boolean;
-	readonly required: boolean;
+	readonly reference: Accessor<string>;
+	readonly readonly: Accessor<boolean>;
+	readonly relevant: Accessor<boolean>;
+	readonly required: Accessor<boolean>;
 	readonly label: null;
 	readonly hint: null;
-	readonly children: Accessor<readonly NodeID[]>;
+	readonly children: Accessor<readonly FormNodeID[]>;
 	readonly valueOptions: null;
 	readonly value: null;
 
 	// Root-specific
-	readonly activeLanguage: Signal<ActiveLanguage>;
+	readonly activeLanguage: Accessor<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>
+	extends DescendantNode<RootDefinition, RootStateSpec, PrimaryInstance, GeneralChildNode>
 	implements
 		RootNode,
+		XFormsXPathElement,
 		EvaluationContext,
-		EvaluationContextRoot,
-		SubscribableDependency,
-		TranslationContext
+		TranslationContext,
+		ClientReactiveSubmittableParentNode<GeneralChildNode>
 {
 	private readonly childrenState: ChildrenState<GeneralChildNode>;
 
-	// InstanceNode
-	readonly hasReadonlyAncestor = () => false;
-	readonly isReadonly = () => false;
-	readonly hasNonRelevantAncestor = () => false;
-	readonly isRelevant = () => true;
+	// XFormsXPathElement
+	override readonly [XPathNodeKindKey] = 'element';
+
+	// DescendantNode
 	protected readonly state: SharedNodeState<RootStateSpec>;
 	protected readonly engineState: EngineState<RootStateSpec>;
 
+	override readonly hasReadonlyAncestor = () => false;
+	override readonly isSelfReadonly = () => false;
+	override readonly isReadonly = () => false;
+	override readonly hasNonRelevantAncestor = () => false;
+	override readonly isSelfRelevant = () => true;
+	override readonly isRelevant = () => true;
+	override readonly isRequired = () => false;
+
 	// RootNode
 	readonly nodeType = 'root';
 	readonly appearances = null;
 	readonly classes: BodyClassList;
 	readonly currentState: MaterializedChildren<CurrentState<RootStateSpec>, GeneralChildNode>;
 	readonly validationState: AncestorNodeValidationState;
+	readonly submissionState: SubmissionState;
 
-	protected readonly instanceDOM: XFormDOM;
-
-	// BaseNode
-	readonly root = this;
-
-	// EvaluationContext
-	readonly evaluator: XFormsXPathEvaluator;
-
-	readonly contextNode: Element;
+	// ClientReactiveSubmittableInstance
+	get submissionDefinition(): SubmissionDefinition {
+		return this.definition.submission;
+	}
 
 	// RootNode
-	override readonly parent = null;
-
 	readonly languages: FormLanguages;
 
-	// TranslationContext
-	get activeLanguage(): ActiveLanguage {
-		return this.engineState.activeLanguage;
-	}
-
-	constructor(xformDOM: XFormDOM, definition: RootDefinition, engineConfig: InstanceConfig) {
-		const reference = definition.nodeset;
+	constructor(parent: PrimaryInstance) {
+		const { definition } = parent;
+		const { nodeset: reference } = definition;
+		const computeReference: Accessor<string> = () => reference;
 
-		super(engineConfig, null, definition, {
-			computeReference: () => reference,
+		super(parent, definition, {
+			computeReference,
 		});
 
-		this.classes = definition.classes;
+		this.classes = parent.classes;
 
 		const childrenState = createChildrenState<Root, GeneralChildNode>(this);
 
 		this.childrenState = childrenState;
+		this.languages = parent.languages;
 
-		const instanceDOM = xformDOM.createInstance();
-		const evaluator = instanceDOM.primaryInstanceEvaluator;
-		const { translations } = evaluator;
-		const { defaultLanguage, languages } = getInitialLanguageState(translations);
 		const sharedStateOptions = {
 			clientStateFactory: this.engineConfig.stateFactory,
 		};
@@ -162,13 +112,13 @@ export class Root
 		const state = createSharedNodeState(
 			this.scope,
 			{
-				activeLanguage: createSignal<ActiveLanguage>(defaultLanguage),
-				reference,
+				activeLanguage: parent.getActiveLanguage,
+				reference: computeReference,
 				label: null,
 				hint: null,
-				readonly: false,
-				relevant: true,
-				required: false,
+				readonly: () => false,
+				relevant: () => true,
+				required: () => false,
 				valueOptions: null,
 				value: null,
 				children: childrenState.childIds,
@@ -184,17 +134,9 @@ export class Root
 			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));
 		this.validationState = createAggregatedViolations(this, sharedStateOptions);
+		this.submissionState = createParentNodeSubmissionState(this);
 	}
 
 	getChildren(): readonly GeneralChildNode[] {
@@ -203,24 +145,14 @@ export class Root
 
 	// 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);
+		this.rootDocument.setLanguage(language);
 
 		return this;
 	}
 
-	// SubscribableDependency
-	override subscribe(): void {
-		super.subscribe();
-
-		this.engineState.activeLanguage;
+	prepareSubmission<ChunkedType extends SubmissionChunkedType = 'monolithic'>(
+		options?: SubmissionOptions<ChunkedType>
+	): Promise<SubmissionResult<ChunkedType>> {
+		return this.rootDocument.prepareSubmission(options);
 	}
 }