@getodk/xforms-engine 0.4.0 → 0.5.0

package/dist/instance/Group.d.ts

@@ -1,31 +1,36 @@
+import { XPathNodeKindKey } from '@getodk/xpath';
 import { Accessor } from 'solid-js';
 import { GroupDefinition, GroupNode, GroupNodeAppearances } from '../client/GroupNode.ts';
+import { FormNodeID } from '../client/identity.ts';
+import { SubmissionState } from '../client/submission/SubmissionState.ts';
 import { TextRange } from '../client/TextRange.ts';
 import { AncestorNodeValidationState } from '../client/validation.ts';
+import { XFormsXPathElement } from '../integration/xpath/adapter/XFormsXPathNode.ts';
 import { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
 import { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
 import { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
 import { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
 import { DescendantNodeSharedStateSpec, DescendantNode } from './abstract/DescendantNode.ts';
 import { GeneralChildNode, GeneralParentNode } from './hierarchy.ts';
-import { NodeID } from './identity.ts';
 import { EvaluationContext } from './internal-api/EvaluationContext.ts';
-import { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
+import { ClientReactiveSubmittableParentNode } from './internal-api/submission/ClientReactiveSubmittableParentNode.ts';
 interface GroupStateSpec extends DescendantNodeSharedStateSpec {
     readonly label: Accessor<TextRange<'label'> | null>;
     readonly hint: null;
-    readonly children: Accessor<readonly NodeID[]>;
+    readonly children: Accessor<readonly FormNodeID[]>;
     readonly valueOptions: null;
     readonly value: null;
 }
-export declare class Group extends DescendantNode<GroupDefinition, GroupStateSpec, GeneralChildNode> implements GroupNode, EvaluationContext, SubscribableDependency {
+export declare class Group extends DescendantNode<GroupDefinition, GroupStateSpec, GeneralParentNode, GeneralChildNode> implements GroupNode, XFormsXPathElement, EvaluationContext, ClientReactiveSubmittableParentNode<GeneralChildNode> {
     private readonly childrenState;
+    readonly [XPathNodeKindKey] = "element";
     protected readonly state: SharedNodeState<GroupStateSpec>;
     protected engineState: EngineState<GroupStateSpec>;
     readonly nodeType = "group";
     readonly appearances: GroupNodeAppearances;
     readonly currentState: MaterializedChildren<CurrentState<GroupStateSpec>, GeneralChildNode>;
     readonly validationState: AncestorNodeValidationState;
+    readonly submissionState: SubmissionState;
     constructor(parent: GeneralParentNode, definition: GroupDefinition);
     getChildren(): readonly GeneralChildNode[];
 }

package/dist/instance/InputControl.d.ts

@@ -0,0 +1,36 @@
+import { XPathNodeKindKey } from '@getodk/xpath';
+import { Accessor } from 'solid-js';
+import { InputDefinition, InputNode, InputNodeAppearances, InputNodeInputValue } from '../client/InputNode.ts';
+import { TextRange } from '../client/TextRange.ts';
+import { ValueType } from '../client/ValueType.ts';
+import { XFormsXPathElement } from '../integration/xpath/adapter/XFormsXPathNode.ts';
+import { RuntimeInputValue, RuntimeValue } from '../lib/codecs/getSharedValueCodec.ts';
+import { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
+import { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
+import { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
+import { Root } from './Root.ts';
+import { ValueNode, ValueNodeStateSpec } from './abstract/ValueNode.ts';
+import { GeneralParentNode } from './hierarchy.ts';
+import { EvaluationContext } from './internal-api/EvaluationContext.ts';
+import { ValidationContext } from './internal-api/ValidationContext.ts';
+import { ClientReactiveSubmittableValueNode } from './internal-api/submission/ClientReactiveSubmittableValueNode.ts';
+export type AnyInputDefinition = {
+    [V in ValueType]: InputDefinition<V>;
+}[ValueType];
+interface InputControlStateSpec<V extends ValueType> extends ValueNodeStateSpec<RuntimeValue<V>> {
+    readonly label: Accessor<TextRange<'label'> | null>;
+    readonly hint: Accessor<TextRange<'hint'> | null>;
+}
+export declare class InputControl<V extends ValueType = ValueType> extends ValueNode<V, InputDefinition<V>, RuntimeValue<V>, RuntimeInputValue<V>> implements InputNode<V>, XFormsXPathElement, EvaluationContext, ValidationContext, ClientReactiveSubmittableValueNode {
+    static from(parent: GeneralParentNode, definition: InputDefinition): AnyInputControl;
+    readonly [XPathNodeKindKey] = "element";
+    protected readonly state: SharedNodeState<InputControlStateSpec<V>>;
+    protected readonly engineState: EngineState<InputControlStateSpec<V>>;
+    readonly nodeType = "input";
+    readonly appearances: InputNodeAppearances;
+    readonly currentState: CurrentState<InputControlStateSpec<V>>;
+    constructor(parent: GeneralParentNode, definition: InputDefinition<V>);
+    setValue(value: InputNodeInputValue<V>): Root;
+}
+export type AnyInputControl = InputControl<'barcode'> | InputControl<'binary'> | InputControl<'boolean'> | InputControl<'date'> | InputControl<'dateTime'> | InputControl<'decimal'> | InputControl<'geopoint'> | InputControl<'geoshape'> | InputControl<'geotrace'> | InputControl<'int'> | InputControl<'intent'> | InputControl<'string'> | InputControl<'time'>;
+export {};

package/dist/instance/ModelValue.d.ts

@@ -1,39 +1,29 @@
-import { ModelValueNode } from '../client/ModelValueNode.ts';
-import { AnyViolation, LeafNodeValidationState } from '../client/validation.ts';
+import { XPathNodeKindKey } from '@getodk/xpath';
+import { ModelValueDefinition, ModelValueNode } from '../client/ModelValueNode.ts';
+import { ValueType } from '../client/ValueType.ts';
+import { XFormsXPathElement } from '../integration/xpath/adapter/XFormsXPathNode.ts';
+import { RuntimeInputValue, RuntimeValue } from '../lib/codecs/getSharedValueCodec.ts';
 import { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
 import { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
 import { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
-import { SimpleAtomicState } from '../lib/reactivity/types.ts';
-import { LeafNodeDefinition } from '../parse/model/LeafNodeDefinition.ts';
-import { DescendantNodeStateSpec, DescendantNode } from './abstract/DescendantNode.ts';
+import { ValueNode, ValueNodeStateSpec } from './abstract/ValueNode.ts';
 import { GeneralParentNode } from './hierarchy.ts';
 import { EvaluationContext } from './internal-api/EvaluationContext.ts';
-import { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
 import { ValidationContext } from './internal-api/ValidationContext.ts';
-import { ValueContext } from './internal-api/ValueContext.ts';
-export interface ModelValueDefinition extends LeafNodeDefinition {
-    readonly bodyElement: null;
-}
-interface ModelValueStateSpec extends DescendantNodeStateSpec<string> {
+import { ClientReactiveSubmittableValueNode } from './internal-api/submission/ClientReactiveSubmittableValueNode.ts';
+interface ModelValueStateSpec<V extends ValueType> extends ValueNodeStateSpec<RuntimeValue<V>> {
     readonly label: null;
     readonly hint: null;
-    readonly children: null;
-    readonly value: SimpleAtomicState<string>;
-    readonly valueOptions: null;
 }
-export declare class ModelValue extends DescendantNode<ModelValueDefinition, ModelValueStateSpec, null> implements ModelValueNode, EvaluationContext, SubscribableDependency, ValidationContext, ValueContext<string> {
-    private readonly validation;
-    protected readonly state: SharedNodeState<ModelValueStateSpec>;
-    protected engineState: EngineState<ModelValueStateSpec>;
+export declare class ModelValue<V extends ValueType = ValueType> extends ValueNode<V, ModelValueDefinition<V>, RuntimeValue<V>, RuntimeInputValue<V>> implements ModelValueNode<V>, XFormsXPathElement, EvaluationContext, ValidationContext, ClientReactiveSubmittableValueNode {
+    static from(parent: GeneralParentNode, definition: ModelValueDefinition): AnyModelValue;
+    readonly [XPathNodeKindKey] = "element";
+    protected readonly state: SharedNodeState<ModelValueStateSpec<V>>;
+    protected readonly engineState: EngineState<ModelValueStateSpec<V>>;
     readonly nodeType = "model-value";
     readonly appearances: null;
-    readonly currentState: CurrentState<ModelValueStateSpec>;
-    get validationState(): LeafNodeValidationState;
-    readonly encodeValue: (value: string) => string;
-    readonly decodeValue: (value: string) => string;
-    constructor(parent: GeneralParentNode, definition: ModelValueDefinition);
-    getViolation(): AnyViolation | null;
-    isBlank(): boolean;
-    getChildren(): readonly [];
+    readonly currentState: CurrentState<ModelValueStateSpec<V>>;
+    constructor(parent: GeneralParentNode, definition: ModelValueDefinition<V>);
 }
+export type AnyModelValue = ModelValue<'barcode'> | ModelValue<'binary'> | ModelValue<'boolean'> | ModelValue<'date'> | ModelValue<'dateTime'> | ModelValue<'decimal'> | ModelValue<'geopoint'> | ModelValue<'geoshape'> | ModelValue<'geotrace'> | ModelValue<'int'> | ModelValue<'intent'> | ModelValue<'string'> | ModelValue<'time'>;
 export {};

package/dist/instance/Note.d.ts

@@ -1,7 +1,10 @@
+import { XPathNodeKindKey } from '@getodk/xpath';
 import { Accessor } from 'solid-js';
 import { NoteNode, NoteNodeAppearances } from '../client/NoteNode.ts';
+import { SubmissionState } from '../client/submission/SubmissionState.ts';
 import { TextRange } from '../client/TextRange.ts';
 import { AnyViolation, LeafNodeValidationState } from '../client/validation.ts';
+import { XFormsXPathElement } from '../integration/xpath/adapter/XFormsXPathNode.ts';
 import { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
 import { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
 import { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
@@ -11,7 +14,7 @@ import { NoteNodeDefinition } from '../parse/model/NoteNodeDefinition.ts';
 import { DescendantNodeStateSpec, DescendantNode } from './abstract/DescendantNode.ts';
 import { GeneralParentNode } from './hierarchy.ts';
 import { EvaluationContext } from './internal-api/EvaluationContext.ts';
-import { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
+import { ClientReactiveSubmittableLeafNode } from './internal-api/submission/ClientReactiveSubmittableLeafNode.ts';
 import { ValidationContext } from './internal-api/ValidationContext.ts';
 import { ValueContext } from './internal-api/ValueContext.ts';
 interface NoteStateSpec extends DescendantNodeStateSpec<string> {
@@ -23,17 +26,21 @@ interface NoteStateSpec extends DescendantNodeStateSpec<string> {
     readonly value: SimpleAtomicState<string>;
     readonly valueOptions: null;
 }
-export declare class Note extends DescendantNode<NoteNodeDefinition, NoteStateSpec, null> implements NoteNode, EvaluationContext, SubscribableDependency, ValidationContext, ValueContext<string> {
+export declare class Note extends DescendantNode<NoteNodeDefinition, NoteStateSpec, GeneralParentNode, null> implements NoteNode, XFormsXPathElement, EvaluationContext, ValidationContext, ValueContext<string>, ClientReactiveSubmittableLeafNode<string> {
     private readonly validation;
+    readonly [XPathNodeKindKey] = "element";
     protected readonly state: SharedNodeState<NoteStateSpec>;
-    protected engineState: EngineState<NoteStateSpec>;
+    protected readonly engineState: EngineState<NoteStateSpec>;
     readonly nodeType = "note";
     readonly appearances: NoteNodeAppearances;
     readonly currentState: CurrentState<NoteStateSpec>;
     get validationState(): LeafNodeValidationState;
+    readonly submissionState: SubmissionState;
+    readonly contextNode: this;
     readonly encodeValue: (value: string) => string;
     readonly decodeValue: (value: string) => string;
     constructor(parent: GeneralParentNode, definition: NoteNodeDefinition);
+    getXPathValue(): string;
     getViolation(): AnyViolation | null;
     isBlank(): boolean;
     getChildren(): readonly [];

package/dist/instance/PrimaryInstance.d.ts

@@ -0,0 +1,84 @@
+import { XPathNodeKindKey } from '@getodk/xpath';
+import { Accessor } from 'solid-js';
+import { ActiveLanguage, FormLanguage, FormLanguages } from '../client/FormLanguage.ts';
+import { FormNodeID } from '../client/identity.ts';
+import { SubmissionChunkedType, SubmissionOptions } from '../client/submission/SubmissionOptions.ts';
+import { SubmissionResult } from '../client/submission/SubmissionResult.ts';
+import { SubmissionState } from '../client/submission/SubmissionState.ts';
+import { AncestorNodeValidationState } from '../client/validation.ts';
+import { XFormsXPathDocument } from '../integration/xpath/adapter/XFormsXPathNode.ts';
+import { EngineXPathEvaluator } from '../integration/xpath/EngineXPathEvaluator.ts';
+import { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
+import { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
+import { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
+import { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
+import { ReactiveScope } from '../lib/reactivity/scope.ts';
+import { BodyClassList } from '../parse/body/BodyDefinition.ts';
+import { ModelDefinition } from '../parse/model/ModelDefinition.ts';
+import { RootDefinition } from '../parse/model/RootDefinition.ts';
+import { SecondaryInstancesDefinition } from '../parse/model/SecondaryInstance/SecondaryInstancesDefinition.ts';
+import { InstanceNode } from './abstract/InstanceNode.ts';
+import { EvaluationContext } from './internal-api/EvaluationContext.ts';
+import { InstanceConfig } from './internal-api/InstanceConfig.ts';
+import { PrimaryInstanceDocument } from './internal-api/PrimaryInstanceDocument.ts';
+import { ClientReactiveSubmittableInstance } from './internal-api/submission/ClientReactiveSubmittableInstance.ts';
+import { TranslationContext } from './internal-api/TranslationContext.ts';
+import { Root } from './Root.ts';
+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;
+    readonly activeLanguage: Accessor<ActiveLanguage>;
+}
+export declare class PrimaryInstance extends InstanceNode<RootDefinition, PrimaryInstanceStateSpec, null, Root> implements PrimaryInstanceDocument, XFormsXPathDocument, TranslationContext, EvaluationContext, ClientReactiveSubmittableInstance {
+    protected readonly state: SharedNodeState<PrimaryInstanceStateSpec>;
+    protected readonly engineState: EngineState<PrimaryInstanceStateSpec>;
+    readonly getChildren: Accessor<readonly Root[]>;
+    readonly hasReadonlyAncestor: () => boolean;
+    readonly isReadonly: () => boolean;
+    readonly hasNonRelevantAncestor: () => boolean;
+    readonly isRelevant: () => boolean;
+    private readonly setActiveLanguage;
+    readonly [XPathNodeKindKey] = "document";
+    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;
+    readonly getActiveLanguage: Accessor<ActiveLanguage>;
+    readonly isAttached: Accessor<boolean>;
+    readonly evaluator: EngineXPathEvaluator;
+    readonly contextNode: this;
+    constructor(scope: ReactiveScope, model: ModelDefinition, secondaryInstances: SecondaryInstancesDefinition, engineConfig: InstanceConfig);
+    /**
+     * @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;
+    prepareSubmission<ChunkedType extends SubmissionChunkedType = 'monolithic'>(options?: SubmissionOptions<ChunkedType>): Promise<SubmissionResult<ChunkedType>>;
+}
+export {};

package/dist/instance/Root.d.ts

@@ -1,57 +1,61 @@
-import { XFormsXPathEvaluator } from '@getodk/xpath';
-import { Accessor, Signal } from 'solid-js';
+import { XPathNodeKindKey } from '@getodk/xpath';
+import { Accessor } from 'solid-js';
 import { ActiveLanguage, FormLanguage, FormLanguages } from '../client/FormLanguage.ts';
+import { FormNodeID } from '../client/identity.ts';
 import { RootNode } from '../client/RootNode.ts';
+import { SubmissionDefinition } from '../client/submission/SubmissionDefinition.ts';
+import { SubmissionChunkedType, SubmissionOptions } from '../client/submission/SubmissionOptions.ts';
+import { SubmissionResult } from '../client/submission/SubmissionResult.ts';
+import { SubmissionState } from '../client/submission/SubmissionState.ts';
 import { AncestorNodeValidationState } from '../client/validation.ts';
+import { XFormsXPathElement } from '../integration/xpath/adapter/XFormsXPathNode.ts';
 import { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
 import { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
 import { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
 import { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
 import { BodyClassList } from '../parse/body/BodyDefinition.ts';
 import { RootDefinition } from '../parse/model/RootDefinition.ts';
-import { XFormDOM } from '../parse/XFormDOM.ts';
-import { InstanceNode } from './abstract/InstanceNode.ts';
+import { DescendantNode } from './abstract/DescendantNode.ts';
 import { GeneralChildNode } from './hierarchy.ts';
-import { NodeID } from './identity.ts';
-import { EvaluationContext, EvaluationContextRoot } from './internal-api/EvaluationContext.ts';
-import { InstanceConfig } from './internal-api/InstanceConfig.ts';
-import { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
+import { EvaluationContext } from './internal-api/EvaluationContext.ts';
+import { ClientReactiveSubmittableParentNode } from './internal-api/submission/ClientReactiveSubmittableParentNode.ts';
 import { TranslationContext } from './internal-api/TranslationContext.ts';
+import { 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;
-    readonly activeLanguage: Signal<ActiveLanguage>;
+    readonly activeLanguage: Accessor<ActiveLanguage>;
 }
-export declare class Root extends InstanceNode<RootDefinition, RootStateSpec, GeneralChildNode> implements RootNode, EvaluationContext, EvaluationContextRoot, SubscribableDependency, TranslationContext {
+export declare class Root extends DescendantNode<RootDefinition, RootStateSpec, PrimaryInstance, GeneralChildNode> implements RootNode, XFormsXPathElement, EvaluationContext, TranslationContext, ClientReactiveSubmittableParentNode<GeneralChildNode> {
     private readonly childrenState;
+    readonly [XPathNodeKindKey] = "element";
+    protected readonly state: SharedNodeState<RootStateSpec>;
+    protected readonly engineState: EngineState<RootStateSpec>;
     readonly hasReadonlyAncestor: () => boolean;
+    readonly isSelfReadonly: () => boolean;
     readonly isReadonly: () => boolean;
     readonly hasNonRelevantAncestor: () => boolean;
+    readonly isSelfRelevant: () => boolean;
     readonly isRelevant: () => boolean;
-    protected readonly state: SharedNodeState<RootStateSpec>;
-    protected readonly engineState: EngineState<RootStateSpec>;
+    readonly isRequired: () => boolean;
     readonly nodeType = "root";
     readonly appearances: null;
     readonly classes: BodyClassList;
     readonly currentState: MaterializedChildren<CurrentState<RootStateSpec>, GeneralChildNode>;
     readonly validationState: AncestorNodeValidationState;
-    protected readonly instanceDOM: XFormDOM;
-    readonly root: this;
-    readonly evaluator: XFormsXPathEvaluator;
-    readonly contextNode: Element;
-    readonly parent: null;
+    readonly submissionState: SubmissionState;
+    get submissionDefinition(): SubmissionDefinition;
     readonly languages: FormLanguages;
-    get activeLanguage(): ActiveLanguage;
-    constructor(xformDOM: XFormDOM, definition: RootDefinition, engineConfig: InstanceConfig);
+    constructor(parent: PrimaryInstance);
     getChildren(): readonly GeneralChildNode[];
     setLanguage(language: FormLanguage): Root;
-    subscribe(): void;
+    prepareSubmission<ChunkedType extends SubmissionChunkedType = 'monolithic'>(options?: SubmissionOptions<ChunkedType>): Promise<SubmissionResult<ChunkedType>>;
 }
 export {};

package/dist/instance/SelectField.d.ts

@@ -1,7 +1,10 @@
+import { XPathNodeKindKey } from '@getodk/xpath';
 import { Accessor } from 'solid-js';
 import { SelectItem, SelectNode, SelectNodeAppearances } from '../client/SelectNode.ts';
 import { TextRange } from '../client/TextRange.ts';
+import { SubmissionState } from '../client/submission/SubmissionState.ts';
 import { AnyViolation, LeafNodeValidationState } from '../client/validation.ts';
+import { XFormsXPathElement } from '../integration/xpath/adapter/XFormsXPathNode.ts';
 import { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
 import { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
 import { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
@@ -12,9 +15,9 @@ import { Root } from './Root.ts';
 import { DescendantNodeStateSpec, DescendantNode } from './abstract/DescendantNode.ts';
 import { GeneralParentNode } from './hierarchy.ts';
 import { EvaluationContext } from './internal-api/EvaluationContext.ts';
-import { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
 import { ValidationContext } from './internal-api/ValidationContext.ts';
 import { ValueContext } from './internal-api/ValueContext.ts';
+import { ClientReactiveSubmittableLeafNode } from './internal-api/submission/ClientReactiveSubmittableLeafNode.ts';
 export interface SelectFieldDefinition extends LeafNodeDefinition {
     readonly bodyElement: AnySelectDefinition;
 }
@@ -25,22 +28,27 @@ interface SelectFieldStateSpec extends DescendantNodeStateSpec<readonly SelectIt
     readonly value: SimpleAtomicState<readonly SelectItem[]>;
     readonly valueOptions: Accessor<readonly SelectItem[]>;
 }
-export declare class SelectField extends DescendantNode<SelectFieldDefinition, SelectFieldStateSpec, null> implements SelectNode, EvaluationContext, SubscribableDependency, ValidationContext, ValueContext<readonly SelectItem[]> {
+export declare class SelectField extends DescendantNode<SelectFieldDefinition, SelectFieldStateSpec, GeneralParentNode, null> implements SelectNode, XFormsXPathElement, EvaluationContext, ValidationContext, ValueContext<readonly SelectItem[]>, ClientReactiveSubmittableLeafNode<readonly SelectItem[]> {
     private readonly selectExclusive;
     private readonly validation;
+    readonly [XPathNodeKindKey] = "element";
     protected readonly state: SharedNodeState<SelectFieldStateSpec>;
     protected engineState: EngineState<SelectFieldStateSpec>;
     readonly nodeType = "select";
     readonly appearances: SelectNodeAppearances;
     readonly currentState: CurrentState<SelectFieldStateSpec>;
     get validationState(): LeafNodeValidationState;
+    readonly submissionState: SubmissionState;
+    readonly contextNode: this;
     readonly encodeValue: (runtimeValue: readonly SelectItem[]) => string;
     readonly decodeValue: (instanceValue: string) => readonly SelectItem[];
     protected readonly getValueOptions: Accessor<readonly SelectItem[]>;
+    protected readonly getValue: Accessor<readonly SelectItem[]>;
     constructor(parent: GeneralParentNode, definition: SelectFieldDefinition);
     protected getSelectItemsByValue(valueOptions?: readonly SelectItem[]): ReadonlyMap<string, SelectItem>;
     protected updateSelectedItemValues(values: readonly string[]): void;
     protected setSelectedItemValue(value: string | null): void;
+    getXPathValue(): string;
     select(selectedItem: SelectItem): Root;
     deselect(deselectedItem: SelectItem): Root;
     getChildren(): readonly [];

package/dist/instance/Subtree.d.ts

@@ -1,30 +1,35 @@
+import { XPathNodeKindKey } from '@getodk/xpath';
 import { Accessor } from 'solid-js';
+import { FormNodeID } from '../client/identity.ts';
+import { SubmissionState } from '../client/submission/SubmissionState.ts';
 import { SubtreeDefinition, SubtreeNode } from '../client/SubtreeNode.ts';
 import { AncestorNodeValidationState } from '../client/validation.ts';
+import { XFormsXPathElement } from '../integration/xpath/adapter/XFormsXPathNode.ts';
 import { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
 import { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
 import { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
 import { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
 import { DescendantNodeSharedStateSpec, DescendantNode } from './abstract/DescendantNode.ts';
 import { GeneralChildNode, GeneralParentNode } from './hierarchy.ts';
-import { NodeID } from './identity.ts';
 import { EvaluationContext } from './internal-api/EvaluationContext.ts';
-import { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
+import { ClientReactiveSubmittableParentNode } from './internal-api/submission/ClientReactiveSubmittableParentNode.ts';
 interface SubtreeStateSpec extends DescendantNodeSharedStateSpec {
     readonly label: null;
     readonly hint: null;
-    readonly children: Accessor<readonly NodeID[]>;
+    readonly children: Accessor<readonly FormNodeID[]>;
     readonly valueOptions: null;
     readonly value: null;
 }
-export declare class Subtree extends DescendantNode<SubtreeDefinition, SubtreeStateSpec, GeneralChildNode> implements SubtreeNode, EvaluationContext, SubscribableDependency {
+export declare class Subtree extends DescendantNode<SubtreeDefinition, SubtreeStateSpec, GeneralParentNode, GeneralChildNode> implements SubtreeNode, XFormsXPathElement, EvaluationContext, ClientReactiveSubmittableParentNode<GeneralChildNode> {
     private readonly childrenState;
+    readonly [XPathNodeKindKey] = "element";
     protected readonly state: SharedNodeState<SubtreeStateSpec>;
-    protected engineState: EngineState<SubtreeStateSpec>;
+    protected readonly engineState: EngineState<SubtreeStateSpec>;
     readonly nodeType = "subtree";
     readonly appearances: null;
     readonly currentState: MaterializedChildren<CurrentState<SubtreeStateSpec>, GeneralChildNode>;
     readonly validationState: AncestorNodeValidationState;
+    readonly submissionState: SubmissionState;
     constructor(parent: GeneralParentNode, definition: SubtreeDefinition);
     getChildren(): readonly GeneralChildNode[];
 }

package/dist/instance/TriggerControl.d.ts

@@ -1,7 +1,10 @@
+import { XPathNodeKindKey } from '@getodk/xpath';
 import { Accessor } from 'solid-js';
 import { TextRange } from '../client/TextRange.ts';
 import { TriggerNode, TriggerNodeDefinition } from '../client/TriggerNode.ts';
+import { SubmissionState } from '../client/submission/SubmissionState.ts';
 import { AnyViolation, LeafNodeValidationState } from '../client/validation.ts';
+import { XFormsXPathElement } from '../integration/xpath/adapter/XFormsXPathNode.ts';
 import { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
 import { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
 import { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
@@ -11,9 +14,9 @@ import { Root } from './Root.ts';
 import { DescendantNodeStateSpec, DescendantNode } from './abstract/DescendantNode.ts';
 import { GeneralParentNode } from './hierarchy.ts';
 import { EvaluationContext } from './internal-api/EvaluationContext.ts';
-import { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
 import { ValidationContext } from './internal-api/ValidationContext.ts';
 import { ValueContext } from './internal-api/ValueContext.ts';
+import { ClientReactiveSubmittableLeafNode } from './internal-api/submission/ClientReactiveSubmittableLeafNode.ts';
 interface TriggerControlStateSpec extends DescendantNodeStateSpec<boolean> {
     readonly label: Accessor<TextRange<'label'> | null>;
     readonly hint: Accessor<TextRange<'hint'> | null>;
@@ -21,17 +24,21 @@ interface TriggerControlStateSpec extends DescendantNodeStateSpec<boolean> {
     readonly value: SimpleAtomicState<boolean>;
     readonly valueOptions: null;
 }
-export declare class TriggerControl extends DescendantNode<TriggerNodeDefinition, TriggerControlStateSpec, null> implements TriggerNode, EvaluationContext, SubscribableDependency, ValidationContext, ValueContext<boolean> {
+export declare class TriggerControl extends DescendantNode<TriggerNodeDefinition, TriggerControlStateSpec, GeneralParentNode, null> implements TriggerNode, XFormsXPathElement, EvaluationContext, ValidationContext, ValueContext<boolean>, ClientReactiveSubmittableLeafNode<boolean> {
     private readonly validation;
+    readonly [XPathNodeKindKey] = "element";
     protected readonly state: SharedNodeState<TriggerControlStateSpec>;
-    protected engineState: EngineState<TriggerControlStateSpec>;
+    protected readonly engineState: EngineState<TriggerControlStateSpec>;
     readonly nodeType = "trigger";
     readonly appearances: UnknownAppearanceDefinition;
     readonly currentState: CurrentState<TriggerControlStateSpec>;
     get validationState(): LeafNodeValidationState;
+    readonly submissionState: SubmissionState;
+    readonly contextNode: this;
     readonly encodeValue: (runtimeValue: boolean) => string;
     readonly decodeValue: (instanceValue: string) => boolean;
     constructor(parent: GeneralParentNode, definition: TriggerNodeDefinition);
+    getXPathValue(): string;
     getViolation(): AnyViolation | null;
     isBlank(): boolean;
     getChildren(): readonly [];

package/dist/instance/abstract/DescendantNode.d.ts

@@ -1,13 +1,15 @@
-import { XFormsXPathEvaluator } from '@getodk/xpath';
+import { XPathNodeKindKey } from '@getodk/xpath';
 import { Accessor } from 'solid-js';
 import { BaseNode } from '../../client/BaseNode.ts';
+import { ActiveLanguage } from '../../client/FormLanguage.ts';
+import { InstanceNodeType } from '../../client/node-types.ts';
+import { PrimaryInstanceXPathChildNode } from '../../integration/xpath/adapter/kind.ts';
+import { XFormsXPathPrimaryInstanceDescendantNode, XFormsXPathPrimaryInstanceDescendantNodeKind } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
+import { EngineXPathEvaluator } from '../../integration/xpath/EngineXPathEvaluator.ts';
 import { AnyDescendantNodeDefinition } from '../../parse/model/DescendentNodeDefinition.ts';
-import { LeafNodeDefinition } from '../../parse/model/LeafNodeDefinition.ts';
 import { AnyNodeDefinition } from '../../parse/model/NodeDefinition.ts';
-import { RepeatInstanceDefinition } from '../../parse/model/RepeatInstanceDefinition.ts';
-import { AnyChildNode, GeneralParentNode, RepeatRange } from '../hierarchy.ts';
+import { AnyChildNode, AnyParentNode } from '../hierarchy.ts';
 import { EvaluationContext } from '../internal-api/EvaluationContext.ts';
-import { SubscribableDependency } from '../internal-api/SubscribableDependency.ts';
 import { Root } from '../Root.ts';
 import { InstanceNodeStateSpec, InstanceNode } from './InstanceNode.ts';
 export interface DescendantNodeSharedStateSpec {
@@ -18,14 +20,18 @@ export interface DescendantNodeSharedStateSpec {
 }
 export type DescendantNodeStateSpec<Value = never> = InstanceNodeStateSpec<Value> & DescendantNodeSharedStateSpec;
 export type DescendantNodeDefinition = Extract<AnyNodeDefinition, AnyDescendantNodeDefinition>;
-export type DescendantNodeParent<Definition extends DescendantNodeDefinition> = Definition extends LeafNodeDefinition ? GeneralParentNode : Definition extends RepeatInstanceDefinition ? RepeatRange : GeneralParentNode;
-export type AnyDescendantNode = DescendantNode<DescendantNodeDefinition, DescendantNodeStateSpec<any>, any>;
+export type AnyDescendantNode = DescendantNode<DescendantNodeDefinition, DescendantNodeStateSpec<any>, any, any>;
 interface DescendantNodeOptions {
     readonly computeReference?: Accessor<string>;
 }
-export declare abstract class DescendantNode<Definition extends DescendantNodeDefinition, Spec extends DescendantNodeStateSpec<any>, Child extends AnyChildNode | null = null> extends InstanceNode<Definition, Spec, Child> implements BaseNode, EvaluationContext, SubscribableDependency {
-    readonly parent: DescendantNodeParent<Definition>;
+export declare abstract class DescendantNode<Definition extends DescendantNodeDefinition, Spec extends DescendantNodeStateSpec<any>, Parent extends AnyParentNode, Child extends AnyChildNode | null = null> extends InstanceNode<Definition, Spec, Parent, Child> implements BaseNode, XFormsXPathPrimaryInstanceDescendantNode, EvaluationContext {
+    readonly parent: Parent;
     readonly definition: Definition;
+    /**
+     * Partial implementation of {@link isAttached}, used to check whether `this`
+     * is present in {@link parent}'s children state.
+     */
+    protected readonly isAttachedDescendant: Accessor<boolean>;
     readonly hasReadonlyAncestor: Accessor<boolean>;
     readonly isSelfReadonly: Accessor<boolean>;
     readonly isReadonly: Accessor<boolean>;
@@ -33,23 +39,25 @@ export declare abstract class DescendantNode<Definition extends DescendantNodeDe
     readonly isSelfRelevant: Accessor<boolean>;
     readonly isRelevant: Accessor<boolean>;
     readonly isRequired: Accessor<boolean>;
-    readonly root: Root;
-    readonly evaluator: XFormsXPathEvaluator;
-    readonly contextNode: Element;
-    constructor(parent: DescendantNodeParent<Definition>, definition: Definition, options?: DescendantNodeOptions);
-    protected createContextNode(parentContextNode: Element, nodeName: string): Element;
     /**
-     * Currently expected to be overridden by...
+     * WARNING! Ideally, this would be an abstract property, defined by each
+     * concrete subclass (or other intermediate abstract classes, where
+     * appropriate). Unfortunately it must be assigned here, so it will be present
+     * for certain XPath DOM adapter functionality **during** each concrete node's
+     * construction.
      *
-     * - 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).
+     * Those subclasses nevertheless override this same property, assigning the
+     * same value, for the purposes of narrowing the XPath node kind semantics
+     * appropriate for each node type.
      */
-    protected initializeContextNode(parentContextNode: Element, nodeName: string): Element;
+    readonly [XPathNodeKindKey]: XFormsXPathPrimaryInstanceDescendantNodeKind;
+    readonly root: Root;
+    abstract readonly nodeType: InstanceNodeType;
+    readonly isAttached: Accessor<boolean>;
+    readonly evaluator: EngineXPathEvaluator;
+    readonly contextNode: PrimaryInstanceXPathChildNode;
+    readonly getActiveLanguage: Accessor<ActiveLanguage>;
+    constructor(parent: Parent, definition: Definition, options?: DescendantNodeOptions);
     /**
      * @package
      *