@getodk/xforms-engine 0.5.0 → 0.7.0

package/src/instance/Subtree.ts

@@ -1,11 +1,12 @@
 import { XPathNodeKindKey } from '@getodk/xpath';
 import type { Accessor } from 'solid-js';
 import type { FormNodeID } from '../client/identity.ts';
-import type { SubmissionState } from '../client/submission/SubmissionState.ts';
+import type { InstanceState } from '../client/serialization/InstanceState.ts';
 import type { SubtreeDefinition, SubtreeNode } from '../client/SubtreeNode.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 { StaticElement } from '../integration/xpath/static-dom/StaticElement.ts';
+import { createParentNodeInstanceState } from '../lib/client-reactivity/instance-state/createParentNodeInstanceState.ts';
 import type { ChildrenState } from '../lib/reactivity/createChildrenState.ts';
 import { createChildrenState } from '../lib/reactivity/createChildrenState.ts';
 import type { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
@@ -17,10 +18,10 @@ import { createSharedNodeState } from '../lib/reactivity/node-state/createShared
 import { createAggregatedViolations } from '../lib/reactivity/validation/createAggregatedViolations.ts';
 import type { DescendantNodeSharedStateSpec } from './abstract/DescendantNode.ts';
 import { DescendantNode } from './abstract/DescendantNode.ts';
-import { buildChildren } from './children.ts';
+import { buildChildren } from './children/buildChildren.ts';
 import type { GeneralChildNode, GeneralParentNode } from './hierarchy.ts';
 import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
-import type { ClientReactiveSubmittableParentNode } from './internal-api/submission/ClientReactiveSubmittableParentNode.ts';
+import type { ClientReactiveSerializableParentNode } from './internal-api/serialization/ClientReactiveSerializableParentNode.ts';
 
 interface SubtreeStateSpec extends DescendantNodeSharedStateSpec {
 	readonly label: null;
@@ -36,7 +37,7 @@ export class Subtree
 		SubtreeNode,
 		XFormsXPathElement,
 		EvaluationContext,
-		ClientReactiveSubmittableParentNode<GeneralChildNode>
+		ClientReactiveSerializableParentNode<GeneralChildNode>
 {
 	private readonly childrenState: ChildrenState<GeneralChildNode>;
 
@@ -49,21 +50,22 @@ export class Subtree
 	// SubtreeNode
 	readonly nodeType = 'subtree';
 	readonly appearances = null;
+	readonly nodeOptions = null;
 	readonly currentState: MaterializedChildren<CurrentState<SubtreeStateSpec>, GeneralChildNode>;
 	readonly validationState: AncestorNodeValidationState;
-	readonly submissionState: SubmissionState;
+	readonly instanceState: InstanceState;
 
-	constructor(parent: GeneralParentNode, definition: SubtreeDefinition) {
-		super(parent, definition);
+	constructor(
+		parent: GeneralParentNode,
+		instanceNode: StaticElement | null,
+		definition: SubtreeDefinition
+	) {
+		super(parent, instanceNode, definition);
 
 		const childrenState = createChildrenState<Subtree, GeneralChildNode>(this);
 
 		this.childrenState = childrenState;
 
-		const sharedStateOptions = {
-			clientStateFactory: this.engineConfig.stateFactory,
-		};
-
 		const state = createSharedNodeState(
 			this.scope,
 			{
@@ -78,7 +80,7 @@ export class Subtree
 				valueOptions: null,
 				value: null,
 			},
-			sharedStateOptions
+			this.instanceConfig
 		);
 
 		this.state = state;
@@ -90,8 +92,8 @@ export class Subtree
 		);
 
 		childrenState.setChildren(buildChildren(this));
-		this.validationState = createAggregatedViolations(this, sharedStateOptions);
-		this.submissionState = createParentNodeSubmissionState(this);
+		this.validationState = createAggregatedViolations(this, this.instanceConfig);
+		this.instanceState = createParentNodeInstanceState(this);
 	}
 
 	getChildren(): readonly GeneralChildNode[] {

package/src/instance/TriggerControl.ts

@@ -2,51 +2,70 @@ import { XPathNodeKindKey } from '@getodk/xpath';
 import type { Accessor } from 'solid-js';
 import type { TextRange } from '../client/TextRange.ts';
 import type { TriggerNode, TriggerNodeDefinition } from '../client/TriggerNode.ts';
-import type { SubmissionState } from '../client/submission/SubmissionState.ts';
-import type { AnyViolation, LeafNodeValidationState } from '../client/validation.ts';
+import type { ValueType } from '../client/ValueType.ts';
+import { ErrorProductionDesignPendingError } from '../error/ErrorProductionDesignPendingError.ts';
 import type { XFormsXPathElement } from '../integration/xpath/adapter/XFormsXPathNode.ts';
-import { createLeafNodeSubmissionState } from '../lib/client-reactivity/submission/createLeafNodeSubmissionState.ts';
-import { createValueState } from '../lib/reactivity/createValueState.ts';
+import type { StaticLeafElement } from '../integration/xpath/static-dom/StaticElement.ts';
+import type { TriggerInputValue, TriggerRuntimeValue } from '../lib/codecs/TriggerCodec.ts';
+import { TriggerCodec } from '../lib/codecs/TriggerCodec.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 { SharedValidationState } from '../lib/reactivity/validation/createValidation.ts';
-import { createValidationState } from '../lib/reactivity/validation/createValidation.ts';
 import type { UnknownAppearanceDefinition } from '../parse/body/appearance/unknownAppearanceParser.ts';
 import type { Root } from './Root.ts';
-import type { DescendantNodeStateSpec } from './abstract/DescendantNode.ts';
-import { DescendantNode } from './abstract/DescendantNode.ts';
+import { ValueNode, type ValueNodeStateSpec } from './abstract/ValueNode.ts';
 import type { GeneralParentNode } from './hierarchy.ts';
 import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
 import type { ValidationContext } from './internal-api/ValidationContext.ts';
-import type { ValueContext } from './internal-api/ValueContext.ts';
-import type { ClientReactiveSubmittableLeafNode } from './internal-api/submission/ClientReactiveSubmittableLeafNode.ts';
+import type { ClientReactiveSerializableValueNode } from './internal-api/serialization/ClientReactiveSerializableValueNode.ts';
 
-interface TriggerControlStateSpec extends DescendantNodeStateSpec<boolean> {
+interface TriggerControlStateSpec extends ValueNodeStateSpec<TriggerRuntimeValue> {
 	readonly label: Accessor<TextRange<'label'> | null>;
 	readonly hint: Accessor<TextRange<'hint'> | null>;
-	readonly children: null;
-	readonly value: SimpleAtomicState<boolean>;
 	readonly valueOptions: null;
 }
 
-const TRIGGER_ASSIGNED_VALUE = 'OK';
+type AnyTriggerNodeDefinition = {
+	[V in ValueType]: TriggerNodeDefinition<V>;
+}[ValueType];
+
+const codec = new TriggerCodec();
 
 export class TriggerControl
-	extends DescendantNode<TriggerNodeDefinition, TriggerControlStateSpec, GeneralParentNode, null>
+	extends ValueNode<
+		'string',
+		TriggerNodeDefinition<'string'>,
+		TriggerRuntimeValue,
+		TriggerInputValue
+	>
 	implements
 		TriggerNode,
 		XFormsXPathElement,
 		EvaluationContext,
 		ValidationContext,
-		ValueContext<boolean>,
-		ClientReactiveSubmittableLeafNode<boolean>
+		ClientReactiveSerializableValueNode
 {
-	private readonly validation: SharedValidationState;
+	static from(
+		parent: GeneralParentNode,
+		instanceNode: StaticLeafElement | null,
+		definition: TriggerNodeDefinition
+	): TriggerControl;
+	static from(
+		parent: GeneralParentNode,
+		instanceNode: StaticLeafElement | null,
+		definition: AnyTriggerNodeDefinition
+	): TriggerControl {
+		if (definition.valueType !== 'string') {
+			throw new ErrorProductionDesignPendingError(
+				`Unsupported trigger value type: ${definition.valueType}`
+			);
+		}
+
+		return new this(parent, instanceNode, definition);
+	}
 
 	// XFormsXPathElement
 	override readonly [XPathNodeKindKey] = 'element';
@@ -58,46 +77,17 @@ export class TriggerControl
 	// TriggerNode
 	readonly nodeType = 'trigger';
 	readonly appearances: UnknownAppearanceDefinition;
+	readonly nodeOptions = null;
 	readonly currentState: CurrentState<TriggerControlStateSpec>;
 
-	get validationState(): LeafNodeValidationState {
-		return this.validation.currentState;
-	}
-
-	readonly submissionState: SubmissionState;
-
-	// ValueContext
-	override readonly contextNode = this;
-	readonly encodeValue: (runtimeValue: boolean) => string;
-	readonly decodeValue: (instanceValue: string) => boolean;
-
-	constructor(parent: GeneralParentNode, definition: TriggerNodeDefinition) {
-		super(parent, definition);
+	private constructor(
+		parent: GeneralParentNode,
+		instanceNode: StaticLeafElement | null,
+		definition: TriggerNodeDefinition<'string'>
+	) {
+		super(parent, instanceNode, definition, codec);
 
 		this.appearances = definition.bodyElement.appearances;
-		this.encodeValue = (runtimeValue) => {
-			return runtimeValue ? TRIGGER_ASSIGNED_VALUE : '';
-		};
-		this.decodeValue = (instanceValue) => {
-			const value = instanceValue.trim();
-
-			switch (value) {
-				case TRIGGER_ASSIGNED_VALUE:
-					return true;
-
-				case '':
-					return false;
-
-				// TODO (robustness principle): Case insensitivity? Handle
-				// XPath-semantic booleans?? Other known/common equivalents?
-				default:
-					throw new Error(`Unexpected trigger value: ${value}`);
-			}
-		};
-
-		const sharedStateOptions = {
-			clientStateFactory: this.engineConfig.stateFactory,
-		};
 
 		const state = createSharedNodeState(
 			this.scope,
@@ -111,40 +101,20 @@ export class TriggerControl
 				hint: createFieldHint(this, definition),
 				children: null,
 				valueOptions: null,
-				value: createValueState(this),
+				value: this.valueState,
+				instanceValue: this.getInstanceValue,
 			},
-			sharedStateOptions
+			this.instanceConfig
 		);
 
 		this.state = state;
 		this.engineState = state.engineState;
 		this.currentState = state.currentState;
-		this.validation = createValidationState(this, sharedStateOptions);
-		this.submissionState = createLeafNodeSubmissionState(this);
-	}
-
-	// XFormsXPathElement
-	override getXPathValue(): string {
-		return this.encodeValue(this.engineState.value);
-	}
-
-	// ValidationContext
-	getViolation(): AnyViolation | null {
-		return this.validation.engineState.violation;
-	}
-
-	isBlank(): boolean {
-		return this.engineState.value == null;
-	}
-
-	// InstanceNode
-	getChildren(): readonly [] {
-		return [];
 	}
 
 	// TriggerNode
-	setValue(value: boolean): Root {
-		this.state.setProperty('value', value);
+	setValue(value: TriggerInputValue): Root {
+		this.setValueState(value);
 
 		return this.root;
 	}

package/src/instance/abstract/DescendantNode.ts

@@ -11,10 +11,11 @@ import type {
 } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
 import { XFORMS_XPATH_NODE_RANGE_KIND } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
 import type { EngineXPathEvaluator } from '../../integration/xpath/EngineXPathEvaluator.ts';
+import type { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
 import { createComputedExpression } from '../../lib/reactivity/createComputedExpression.ts';
 import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
-import type { AnyDescendantNodeDefinition } from '../../parse/model/DescendentNodeDefinition.ts';
 import type { AnyNodeDefinition } from '../../parse/model/NodeDefinition.ts';
+import type { DescendantNodeInitOptions } from '../children/DescendantNodeInitOptions.ts';
 import type { AnyChildNode, AnyParentNode, RepeatRange } from '../hierarchy.ts';
 import type { EvaluationContext } from '../internal-api/EvaluationContext.ts';
 import type { RepeatInstance } from '../repeat/RepeatInstance.ts';
@@ -35,11 +36,7 @@ export type DescendantNodeStateSpec<Value = never> =
 	& InstanceNodeStateSpec<Value>
 	& DescendantNodeSharedStateSpec;
 
-// prettier-ignore
-export type DescendantNodeDefinition = Extract<
-	AnyNodeDefinition,
-	AnyDescendantNodeDefinition
->;
+export type DescendantNodeDefinition = AnyNodeDefinition;
 
 export type AnyDescendantNode = DescendantNode<
 	DescendantNodeDefinition,
@@ -55,6 +52,13 @@ interface DescendantNodeOptions {
 	readonly computeReference?: Accessor<string>;
 }
 
+/**
+ * @todo Unify constructor signatures of {@link DescendantNode} and its
+ * subclasses, which will simplify the branchy logic of child node construction
+ * and minimize internal churn as common themes evolve. A good starting point is
+ * beginning to form in {@link DescendantNodeInitOptions} (not to be confused
+ * with the current module-local {@link DescendantNodeOptions}).
+ */
 export abstract class DescendantNode<
 		Definition extends DescendantNodeDefinition,
 		// eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -133,10 +137,11 @@ export abstract class DescendantNode<
 
 	constructor(
 		override readonly parent: Parent,
+		override readonly instanceNode: StaticElement | null,
 		override readonly definition: Definition,
 		options?: DescendantNodeOptions
 	) {
-		super(parent.engineConfig, parent, definition, options);
+		super(parent.instanceConfig, parent, instanceNode, definition, options);
 
 		if (this.isRoot()) {
 			this.root = this;
@@ -147,7 +152,7 @@ export abstract class DescendantNode<
 		const { evaluator } = parent;
 
 		// See notes on property declaration
-		if (definition.type === 'repeat-range') {
+		if (definition.type === 'repeat') {
 			this[XPathNodeKindKey] = XFORMS_XPATH_NODE_RANGE_KIND;
 		} else {
 			this[XPathNodeKindKey] = 'element';

package/src/instance/abstract/InstanceNode.ts

@@ -4,7 +4,7 @@ import type { BaseNode } from '../../client/BaseNode.ts';
 import type { NodeAppearances } from '../../client/NodeAppearances.ts';
 import type { FormNodeID } from '../../client/identity.ts';
 import type { InstanceNodeType as ClientInstanceNodeType } from '../../client/node-types.ts';
-import type { SubmissionState } from '../../client/submission/SubmissionState.ts';
+import type { InstanceState } from '../../client/serialization/InstanceState.ts';
 import type { NodeValidationState } from '../../client/validation.ts';
 import type { ActiveLanguage, TextRange } from '../../index.ts';
 import type { EngineXPathEvaluator } from '../../integration/xpath/EngineXPathEvaluator.ts';
@@ -13,6 +13,8 @@ import type {
 	XFormsXPathPrimaryInstanceNodeKind,
 } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
 import type { PrimaryInstanceXPathNode } from '../../integration/xpath/adapter/kind.ts';
+import type { StaticDocument } from '../../integration/xpath/static-dom/StaticDocument.ts';
+import type { StaticElement } from '../../integration/xpath/static-dom/StaticElement.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';
@@ -20,6 +22,7 @@ import type { SharedNodeState } from '../../lib/reactivity/node-state/createShar
 import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
 import { createReactiveScope } from '../../lib/reactivity/scope.ts';
 import type { SimpleAtomicState } from '../../lib/reactivity/types.ts';
+import { createUniqueId } from '../../lib/unique-id.ts';
 import type { AnyNodeDefinition } from '../../parse/model/NodeDefinition.ts';
 import type { PrimaryInstance } from '../PrimaryInstance.ts';
 import type { Root } from '../Root.ts';
@@ -34,6 +37,12 @@ export interface BaseEngineNode extends Omit<BaseNode, 'nodeType'> {
 	readonly nodeType: EngineInstanceNodeType;
 }
 
+// prettier-ignore
+export type InstanceNodeValueOptionsStateSpec =
+	| Accessor<null>
+	| Accessor<readonly unknown[]>
+	| null
+
 export interface InstanceNodeStateSpec<Value = never> {
 	readonly reference: Accessor<string> | string;
 	readonly readonly: Accessor<boolean> | boolean;
@@ -42,7 +51,7 @@ export interface InstanceNodeStateSpec<Value = never> {
 	readonly label: Accessor<TextRange<'label'> | null> | null;
 	readonly hint: Accessor<TextRange<'hint'> | null> | null;
 	readonly children: Accessor<readonly FormNodeID[]> | null;
-	readonly valueOptions: Accessor<null> | Accessor<readonly unknown[]> | null;
+	readonly valueOptions: InstanceNodeValueOptionsStateSpec;
 	readonly value: Signal<Value> | SimpleAtomicState<Value> | null;
 }
 
@@ -136,11 +145,13 @@ export abstract class InstanceNode<
 
 	abstract readonly appearances: NodeAppearances<Definition>;
 
+	abstract readonly nodeOptions: object | null;
+
 	abstract readonly currentState: InstanceNodeCurrentState<Spec, Child>;
 
 	abstract readonly validationState: NodeValidationState;
 
-	abstract readonly submissionState: SubmissionState;
+	abstract readonly instanceState: InstanceState;
 
 	// EvaluationContext: instance-global/shared
 	abstract readonly evaluator: EngineXPathEvaluator;
@@ -161,7 +172,7 @@ export abstract class InstanceNode<
 			);
 		}
 
-		return `${parent.contextReference()}/${definition.nodeName}`;
+		return `${parent.contextReference()}/${definition.qualifiedName.getPrefixedName()}`;
 	};
 
 	// EvaluationContext: node-specific
@@ -178,8 +189,9 @@ export abstract class InstanceNode<
 		this as AnyInstanceNode as PrimaryInstanceXPathNode;
 
 	constructor(
-		readonly engineConfig: InstanceConfig,
+		readonly instanceConfig: InstanceConfig,
 		readonly parent: Parent,
+		readonly instanceNode: StaticDocument | StaticElement | null,
 		readonly definition: Definition,
 		options?: InstanceNodeOptions
 	) {
@@ -200,8 +212,8 @@ export abstract class InstanceNode<
 		this.computeReference = options?.computeReference ?? this.computeChildStepReference;
 
 		this.scope = options?.scope ?? createReactiveScope();
-		this.engineConfig = engineConfig;
-		this.nodeId = nodeID(engineConfig.createUniqueId());
+		this.instanceConfig = instanceConfig;
+		this.nodeId = nodeID(createUniqueId());
 		this.definition = definition;
 	}
 

package/src/instance/abstract/ValueNode.ts

@@ -2,11 +2,12 @@ import { XPathNodeKindKey } from '@getodk/xpath';
 import type { Accessor } from 'solid-js';
 import type { BaseValueNode } from '../../client/BaseValueNode.ts';
 import type { LeafNodeType as ValueNodeType } from '../../client/node-types.ts';
-import type { SubmissionState } from '../../client/submission/SubmissionState.ts';
+import type { InstanceState } from '../../client/serialization/InstanceState.ts';
 import type { AnyViolation, LeafNodeValidationState } from '../../client/validation.ts';
 import type { ValueType } from '../../client/ValueType.ts';
 import type { XFormsXPathElement } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
-import { createValueNodeSubmissionState } from '../../lib/client-reactivity/submission/createValueNodeSubmissionState.ts';
+import type { StaticLeafElement } from '../../integration/xpath/static-dom/StaticElement.ts';
+import { createValueNodeInstanceState } from '../../lib/client-reactivity/instance-state/createValueNodeInstanceState.ts';
 import type {
 	RuntimeValueSetter,
 	RuntimeValueState,
@@ -26,7 +27,7 @@ import type {
 	DecodeInstanceValue,
 	InstanceValueContext,
 } from '../internal-api/InstanceValueContext.ts';
-import type { ClientReactiveSubmittableValueNode } from '../internal-api/submission/ClientReactiveSubmittableValueNode.ts';
+import type { ClientReactiveSerializableValueNode } from '../internal-api/serialization/ClientReactiveSerializableValueNode.ts';
 import type { ValidationContext } from '../internal-api/ValidationContext.ts';
 import type { DescendantNodeStateSpec } from './DescendantNode.ts';
 import { DescendantNode } from './DescendantNode.ts';
@@ -35,7 +36,6 @@ export type ValueNodeDefinition<V extends ValueType> = LeafNodeDefinition<V>;
 
 export interface ValueNodeStateSpec<RuntimeValue> extends DescendantNodeStateSpec<RuntimeValue> {
 	readonly children: null;
-	readonly valueOptions: null;
 	readonly value: SimpleAtomicState<RuntimeValue>;
 	readonly instanceValue: Accessor<string>;
 }
@@ -53,7 +53,7 @@ export abstract class ValueNode<
 		EvaluationContext,
 		InstanceValueContext,
 		ValidationContext,
-		ClientReactiveSubmittableValueNode
+		ClientReactiveSerializableValueNode
 {
 	protected readonly validation: SharedValidationState;
 	protected readonly getInstanceValue: Accessor<string>;
@@ -81,21 +81,20 @@ export abstract class ValueNode<
 		return this.validation.currentState;
 	}
 
-	readonly submissionState: SubmissionState;
+	readonly instanceState: InstanceState;
 
 	constructor(
 		parent: GeneralParentNode,
+		override readonly instanceNode: StaticLeafElement | null,
 		definition: Definition,
 		codec: ValueCodec<V, RuntimeValue, RuntimeInputValue>
 	) {
-		super(parent, definition);
+		super(parent, instanceNode, definition);
 
 		this.valueType = definition.valueType;
 		this.decodeInstanceValue = codec.decodeInstanceValue;
 
-		const instanceValueState = createInstanceValueState(this, {
-			initialValueSource: 'FORM_DEFAULT',
-		});
+		const instanceValueState = createInstanceValueState(this);
 		const valueState = codec.createRuntimeValueState(instanceValueState);
 
 		const [getInstanceValue] = instanceValueState;
@@ -103,12 +102,12 @@ export abstract class ValueNode<
 
 		this.getInstanceValue = getInstanceValue;
 		this.setValueState = setValueState;
-		this.getXPathValue = getInstanceValue;
+		this.getXPathValue = () => {
+			return this.getInstanceValue();
+		};
 		this.valueState = valueState;
-		this.validation = createValidationState(this, {
-			clientStateFactory: this.engineConfig.stateFactory,
-		});
-		this.submissionState = createValueNodeSubmissionState(this);
+		this.validation = createValidationState(this, this.instanceConfig);
+		this.instanceState = createValueNodeInstanceState(this);
 	}
 
 	// ValidationContext

package/src/instance/children/DescendantNodeInitOptions.ts

@@ -0,0 +1,35 @@
+import type { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
+import type { ChildNodeDefinition } from '../../parse/model/NodeDefinition.ts';
+import type { DescendantNode } from '../abstract/DescendantNode.ts';
+import type { childrenInitOptions } from './childrenInitOptions.ts';
+
+/**
+ * @todo We could pretty significantly simplify downstream child node
+ * construction logic, if we break this down into a tagged union (essentially
+ * moving the branchy type refinement aspects up the stack, probably trimming
+ * the construction logic itself down to a switch statement). At which point,
+ * it'd also probably be easier to reason about each of those constructors
+ * accepting input exactly as it's represented as a member of this hypothetical
+ * tagged union. Something like this:
+ *
+ * - Revise each concrete {@link DescendantNode} class to accept an options-like
+ *   object suitable for its construction, each respectively defined by an
+ *   interface whose name is consistent with that node
+ * - Update this type to be a union of those interfaces
+ * - Implement that in {@link childrenInitOptions}
+ * - Update downstream construction to switch over whatever narrows the union
+ * - Bonus points: revise each concrete {@link DescendantNode} to use a common
+ *   constructor API (i.e. a static `from` method, since several such classes
+ *   already have private constructors). Then downstream isn't even a switch
+ *   statement, it's just a lookup table.
+ *
+ * @todo As of this commit, and as now mentioned on {@link DescendantNode}, and
+ * as discussed in
+ * {@link https://github.com/getodk/web-forms/pull/352#discussion_r2008237762}:
+ * this interface is intended as an intermediate step toward these goals.
+ */
+export interface DescendantNodeInitOptions {
+	readonly childNodeset: string;
+	readonly definition: ChildNodeDefinition;
+	readonly instanceNodes: readonly StaticElement[];
+}