@getodk/xforms-engine 0.4.0 → 0.5.0

package/src/instance/abstract/ValueNode.ts

@@ -0,0 +1,127 @@
+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 { 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 {
+	RuntimeValueSetter,
+	RuntimeValueState,
+	ValueCodec,
+} from '../../lib/codecs/ValueCodec.ts';
+import { createInstanceValueState } from '../../lib/reactivity/createInstanceValueState.ts';
+import type { CurrentState } from '../../lib/reactivity/node-state/createCurrentState.ts';
+import type { EngineState } from '../../lib/reactivity/node-state/createEngineState.ts';
+import type { SharedNodeState } from '../../lib/reactivity/node-state/createSharedNodeState.ts';
+import type { SimpleAtomicState } from '../../lib/reactivity/types.ts';
+import type { SharedValidationState } from '../../lib/reactivity/validation/createValidation.ts';
+import { createValidationState } from '../../lib/reactivity/validation/createValidation.ts';
+import { LeafNodeDefinition } from '../../parse/model/LeafNodeDefinition.ts';
+import type { GeneralParentNode } from '../hierarchy.ts';
+import type { EvaluationContext } from '../internal-api/EvaluationContext.ts';
+import type {
+	DecodeInstanceValue,
+	InstanceValueContext,
+} from '../internal-api/InstanceValueContext.ts';
+import type { ClientReactiveSubmittableValueNode } from '../internal-api/submission/ClientReactiveSubmittableValueNode.ts';
+import type { ValidationContext } from '../internal-api/ValidationContext.ts';
+import type { DescendantNodeStateSpec } from './DescendantNode.ts';
+import { DescendantNode } from './DescendantNode.ts';
+
+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>;
+}
+
+export abstract class ValueNode<
+		V extends ValueType,
+		Definition extends ValueNodeDefinition<V>,
+		RuntimeValue extends RuntimeInputValue,
+		RuntimeInputValue = RuntimeValue,
+	>
+	extends DescendantNode<Definition, ValueNodeStateSpec<RuntimeValue>, GeneralParentNode, null>
+	implements
+		BaseValueNode<V, RuntimeValue>,
+		XFormsXPathElement,
+		EvaluationContext,
+		InstanceValueContext,
+		ValidationContext,
+		ClientReactiveSubmittableValueNode
+{
+	protected readonly validation: SharedValidationState;
+	protected readonly getInstanceValue: Accessor<string>;
+	protected readonly valueState: RuntimeValueState<RuntimeValue>;
+	protected readonly setValueState: RuntimeValueSetter<RuntimeInputValue>;
+
+	// XFormsXPathElement
+	override readonly [XPathNodeKindKey] = 'element';
+	override readonly getXPathValue: () => string;
+
+	// InstanceNode
+	protected abstract override readonly state: SharedNodeState<ValueNodeStateSpec<RuntimeValue>>;
+	protected abstract override readonly engineState: EngineState<ValueNodeStateSpec<RuntimeValue>>;
+
+	// InstanceValueContext
+	readonly decodeInstanceValue: DecodeInstanceValue;
+
+	// BaseValueNode
+	abstract override readonly nodeType: ValueNodeType;
+	readonly valueType: V;
+
+	abstract override readonly currentState: CurrentState<ValueNodeStateSpec<RuntimeValue>>;
+
+	get validationState(): LeafNodeValidationState {
+		return this.validation.currentState;
+	}
+
+	readonly submissionState: SubmissionState;
+
+	constructor(
+		parent: GeneralParentNode,
+		definition: Definition,
+		codec: ValueCodec<V, RuntimeValue, RuntimeInputValue>
+	) {
+		super(parent, definition);
+
+		this.valueType = definition.valueType;
+		this.decodeInstanceValue = codec.decodeInstanceValue;
+
+		const instanceValueState = createInstanceValueState(this, {
+			initialValueSource: 'FORM_DEFAULT',
+		});
+		const valueState = codec.createRuntimeValueState(instanceValueState);
+
+		const [getInstanceValue] = instanceValueState;
+		const [, setValueState] = valueState;
+
+		this.getInstanceValue = getInstanceValue;
+		this.setValueState = setValueState;
+		this.getXPathValue = getInstanceValue;
+		this.valueState = valueState;
+		this.validation = createValidationState(this, {
+			clientStateFactory: this.engineConfig.stateFactory,
+		});
+		this.submissionState = createValueNodeSubmissionState(this);
+	}
+
+	// ValidationContext
+	getViolation(): AnyViolation | null {
+		return this.validation.engineState.violation;
+	}
+
+	isBlank(): boolean {
+		return this.getInstanceValue() === '';
+	}
+
+	// InstanceNode
+	getChildren(): readonly [] {
+		return [];
+	}
+}

package/src/instance/children.ts

@@ -1,5 +1,7 @@
 import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
 import type { GroupDefinition } from '../client/GroupNode.ts';
+import type { InputDefinition } from '../client/InputNode.ts';
+import type { ModelValueDefinition } from '../client/ModelValueNode.ts';
 import type { SubtreeDefinition } from '../client/SubtreeNode.ts';
 import type { TriggerNodeDefinition } from '../client/TriggerNode.ts';
 import type { RangeNodeDefinition } from '../client/unsupported/RangeNode.ts';
@@ -11,14 +13,13 @@ import { NoteNodeDefinition } from '../parse/model/NoteNodeDefinition.ts';
 import type { SubtreeDefinition as ModelSubtreeDefinition } from '../parse/model/SubtreeDefinition.ts';
 import { Group } from './Group.ts';
 import type { GeneralChildNode, GeneralParentNode } from './hierarchy.ts';
-import { ModelValue, type ModelValueDefinition } from './ModelValue.ts';
+import { InputControl } from './InputControl.ts';
+import { ModelValue } from './ModelValue.ts';
 import { Note } from './Note.ts';
 import { RepeatRangeControlled } from './repeat/RepeatRangeControlled.ts';
 import { RepeatRangeUncontrolled } from './repeat/RepeatRangeUncontrolled.ts';
 import type { SelectFieldDefinition } from './SelectField.ts';
 import { SelectField } from './SelectField.ts';
-import type { StringFieldDefinition } from './StringField.ts';
-import { StringField } from './StringField.ts';
 import { Subtree } from './Subtree.ts';
 import { TriggerControl } from './TriggerControl.ts';
 import { RangeControl } from './unsupported/RangeControl.ts';
@@ -39,8 +40,8 @@ type AnyUnsupportedControlDefinition =
 // prettier-ignore
 type ControlNodeDefinition =
 	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| InputDefinition
 	| SelectFieldDefinition
-	| StringFieldDefinition
 	| TriggerNodeDefinition
 	| AnyUnsupportedControlDefinition;
 
@@ -52,9 +53,7 @@ const isModelValueDefinition = (
 	return definition.bodyElement == null;
 };
 
-const isStringFieldDefinition = (
-	definition: ControlNodeDefinition
-): definition is StringFieldDefinition => {
+const isInputDefinition = (definition: ControlNodeDefinition): definition is InputDefinition => {
 	return definition.bodyElement.type === 'input';
 };
 
@@ -121,11 +120,11 @@ export const buildChildren = (parent: GeneralParentNode): GeneralChildNode[] =>
 				const leafChild: AnyLeafNodeDefinition = child;
 
 				if (isModelValueDefinition(leafChild)) {
-					return new ModelValue(parent, leafChild);
+					return ModelValue.from(parent, leafChild);
 				}
 
-				if (isStringFieldDefinition(leafChild)) {
-					return new StringField(parent, leafChild);
+				if (isInputDefinition(leafChild)) {
+					return InputControl.from(parent, leafChild);
 				}
 
 				if (isSelectFieldDefinition(leafChild)) {

package/src/instance/hierarchy.ts

@@ -1,12 +1,13 @@
 import type { Group } from './Group.ts';
-import type { ModelValue } from './ModelValue.ts';
+import type { AnyInputControl } from './InputControl.ts';
+import type { AnyModelValue } from './ModelValue.ts';
 import type { Note } from './Note.ts';
+import type { PrimaryInstance } from './PrimaryInstance.ts';
 import type { RepeatInstance } from './repeat/RepeatInstance.ts';
 import type { RepeatRangeControlled } from './repeat/RepeatRangeControlled.ts';
 import type { RepeatRangeUncontrolled } from './repeat/RepeatRangeUncontrolled.ts';
 import type { Root } from './Root.ts';
 import type { SelectField } from './SelectField.ts';
-import type { StringField } from './StringField.ts';
 import type { Subtree } from './Subtree.ts';
 import type { TriggerControl } from './TriggerControl.ts';
 import type { RangeControl } from './unsupported/RangeControl.ts';
@@ -16,7 +17,7 @@ import type { UploadControl } from './unsupported/UploadControl.ts';
 export type RepeatRange = RepeatRangeControlled | RepeatRangeUncontrolled;
 
 // prettier-ignore
-export type UnsupportedControl =
+export type AnyUnsupportedControl =
 	| RangeControl
 	| RankControl
 	| UploadControl;
@@ -24,21 +25,23 @@ export type UnsupportedControl =
 // prettier-ignore
 export type AnyNode =
 	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| PrimaryInstance
 	| Root
 	| Group
 	| Subtree
 	| RepeatRange
 	| RepeatInstance
 	| Note
-	| ModelValue
-	| StringField
+	| AnyModelValue
+	| AnyInputControl
 	| SelectField
 	| TriggerControl
-	| UnsupportedControl;
+	| AnyUnsupportedControl;
 
 // prettier-ignore
 export type AnyParentNode =
 	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| PrimaryInstance
 	| Root
 	| Group
 	| Subtree
@@ -56,16 +59,17 @@ export type GeneralParentNode =
 // prettier-ignore
 export type AnyChildNode =
 	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| Root
 	| Group
 	| Subtree
 	| RepeatRange
 	| RepeatInstance
-	| ModelValue
+	| AnyModelValue
 	| Note
-	| StringField
+	| AnyInputControl
 	| SelectField
 	| TriggerControl
-	| UnsupportedControl;
+	| AnyUnsupportedControl;
 
 // prettier-ignore
 export type GeneralChildNode =
@@ -73,19 +77,19 @@ export type GeneralChildNode =
 	| Group
 	| Subtree
 	| RepeatRange
-	| ModelValue
+	| AnyModelValue
 	| Note
-	| StringField
+	| AnyInputControl
 	| SelectField
 	| TriggerControl
-	| UnsupportedControl;
+	| AnyUnsupportedControl;
 
 // prettier-ignore
 export type AnyValueNode =
 	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
-	| ModelValue
+	| AnyModelValue
 	| Note
-	| StringField
+	| AnyInputControl
 	| SelectField
 	| TriggerControl
-	| UnsupportedControl;
+	| AnyUnsupportedControl;

package/src/instance/identity.ts

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

package/src/instance/index.ts

@@ -1,24 +1,32 @@
 import { identity } from '@getodk/common/lib/identity.ts';
+import { getOwner } from 'solid-js';
+import type { EngineConfig } from '../client/EngineConfig.ts';
 import type { RootNode } from '../client/RootNode.ts';
+import { MISSING_RESOURCE_BEHAVIOR } from '../client/constants.ts';
 import type {
 	InitializeFormOptions as BaseInitializeFormOptions,
 	FormResource,
 	InitializeForm,
 } from '../client/index.ts';
 import { retrieveSourceXMLResource } from '../instance/resource.ts';
+import { createReactiveScope } from '../lib/reactivity/scope.ts';
 import { createUniqueId } from '../lib/unique-id.ts';
+import { XFormDOM } from '../parse/XFormDOM.ts';
 import { XFormDefinition } from '../parse/XFormDefinition.ts';
-import { Root } from './Root.ts';
+import { SecondaryInstancesDefinition } from '../parse/model/SecondaryInstance/SecondaryInstancesDefinition.ts';
+import { PrimaryInstance } from './PrimaryInstance.ts';
 import type { InstanceConfig } from './internal-api/InstanceConfig.ts';
 
 interface InitializeFormOptions extends BaseInitializeFormOptions {
 	readonly config: Partial<InstanceConfig>;
 }
 
-const buildInstanceConfig = (options: Partial<InstanceConfig> = {}): InstanceConfig => {
+const buildInstanceConfig = (options: EngineConfig = {}): InstanceConfig => {
 	return {
-		createUniqueId: options.createUniqueId ?? createUniqueId,
-		fetchResource: options.fetchResource ?? fetch,
+		createUniqueId,
+		fetchFormDefinition: options.fetchFormDefinition ?? fetch,
+		fetchFormAttachment: options.fetchFormAttachment ?? fetch,
+		missingResourceBehavior: options.missingResourceBehavior ?? MISSING_RESOURCE_BEHAVIOR.DEFAULT,
 		stateFactory: options.stateFactory ?? identity,
 	};
 };
@@ -27,11 +35,21 @@ export const initializeForm = async (
 	input: FormResource,
 	options: Partial<InitializeFormOptions> = {}
 ): Promise<RootNode> => {
+	const owner = getOwner();
+	const scope = createReactiveScope({ owner });
 	const engineConfig = buildInstanceConfig(options.config);
-	const sourceXML = await retrieveSourceXMLResource(input, engineConfig);
-	const form = new XFormDefinition(sourceXML);
+	const sourceXML = await retrieveSourceXMLResource(input, {
+		fetchResource: engineConfig.fetchFormDefinition,
+	});
+	const xformDOM = XFormDOM.from(sourceXML);
+	const secondaryInstances = await SecondaryInstancesDefinition.load(xformDOM, {
+		fetchResource: engineConfig.fetchFormAttachment,
+		missingResourceBehavior: engineConfig.missingResourceBehavior,
+	});
+	const form = new XFormDefinition(xformDOM);
+	const primaryInstance = new PrimaryInstance(scope, form.model, secondaryInstances, engineConfig);
 
-	return new Root(form.xformDOM, form.model.root, engineConfig);
+	return primaryInstance.root;
 };
 
 initializeForm satisfies InitializeForm;

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

@@ -1,12 +1,16 @@
-import type { XFormsXPathEvaluator } from '@getodk/xpath';
 import type { Accessor } from 'solid-js';
+import type { engineDOMAdapter } from '../../integration/xpath/adapter/engineDOMAdapter.ts';
+import type { EngineXPathNode } from '../../integration/xpath/adapter/kind.ts';
+import type { EngineXPathEvaluator } from '../../integration/xpath/EngineXPathEvaluator.ts';
+import type { StaticNode } from '../../integration/xpath/static-dom/StaticNode.ts';
+import type { createComputedExpression } from '../../lib/reactivity/createComputedExpression.ts';
+import type { createTranslationState } from '../../lib/reactivity/createTranslationState.ts';
 import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
 import type { DependentExpression } from '../../parse/expression/abstract/DependentExpression.ts';
-import type { SubscribableDependency } from './SubscribableDependency.ts';
+import type { InstanceNode } from '../abstract/InstanceNode.ts';
+import type { PrimaryInstance } from '../PrimaryInstance.ts';
 import type { TranslationContext } from './TranslationContext.ts';
 
-export interface EvaluationContextRoot extends SubscribableDependency, TranslationContext {}
-
 /**
  * Provides a common interface to establish context for XPath-based
  * computations, i.e. to evaluate {@link DependentExpression}s where:
@@ -18,23 +22,66 @@ export interface EvaluationContextRoot extends SubscribableDependency, Translati
  * - the expression may be dependent on the form's currently active language
  *   (e.g. `jr:itext`)
  * - any dynamic case is expected to be internally reactive
+ *
+ * Historical note: we previously utilized static analysis and a related
+ * abstraction to set up reactive subscriptions to node references, values, and
+ * other pertinent state changes warranting an expression's recomputation. Those
+ * are still described above because they provide useful insight for the
+ * **effect** of evaluating a given {@link DependentExpression}, with a given
+ * {@link EvaluationContext}.
+ *
+ * The reactive subscription mechanism has since been largely replaced, with the
+ * engine's implementation of {@link EngineXPathEvaluator} and its corresponding
+ * {@link engineDOMAdapter | XPath DOM adapter implementation}.
+ *
+ * @todo There is still one notable exception: translation expressions (i.e.
+ * expressions calling {@link https://getodk.github.io/xforms-spec/#fn:jr:itext}
+ * | `jr:itext`). We still perform analysis to identify such calls, and when
+ * evaluating those expressions we still explicitly subscribe to the form's
+ * active language state. A further refactor, moving more of the responsibility
+ * for translation state up out of `@getodk/xpath` into the engine, would likely
+ * allow us to further simplify the engine's reactive XPath recomputation
+ * approach.
+ *
+ * @see {@link createTranslationState} for additional context.
  */
-export interface EvaluationContext {
+export interface EvaluationContext extends TranslationContext {
+	/**
+	 * Used to determine whether {@link contextNode} is attached to its
+	 * {@link EngineXPathNode} document hierarchy.
+	 *
+	 * - If this function returns `true`: expressions are evaluated as defined.
+	 * - If this function returns `false`: expressions are evaluated to either an
+	 *   explicit default value (if provided) or an implicit default value
+	 *   appropriate for the requested result type.
+	 *
+	 * @see {@link createComputedExpression} for further detail on the latter.
+	 */
+	readonly isAttached: Accessor<boolean>;
+
 	readonly scope: ReactiveScope;
-	readonly evaluator: XFormsXPathEvaluator;
-	readonly root: EvaluationContextRoot;
+	readonly evaluator: EngineXPathEvaluator;
 
 	/**
 	 * Produces the current absolute reference to the {@link contextNode}, where
-	 * the absolute `/` resolves to the active form state's primary instance root.
+	 * the AbsoluteLocationPath expression `/` resolves to the active
+	 * {@link PrimaryInstance}, and each Step and/or position Predicate from there
+	 * corresponds to the node hierarchy descending from there.
 	 */
 	readonly contextReference: Accessor<string>;
 
-	readonly contextNode: Node;
-
 	/**
-	 * Resolves nodes corresponding to the provided node-set reference, possibly
-	 * relative to the {@link EvaluationContext.contextNode}.
+	 * Note: in most cases, implementations of {@link EvaluationContext} will
+	 * **also** be an implementation of {@link EngineXPathNode} (as concrete
+	 * implementations of {@link InstanceNode}). This property is an intentional
+	 * indirection which:
+	 *
+	 * - Expresses only the much more limited set of properties which must be
+	 *   present to initialize computations during those nodes' construction.
+	 *
+	 * - Allows for a handful of cases where an {@link InstanceNode} provides the
+	 *   requisite facilities for evaluating expressions in a {@link StaticNode}'s
+	 *   context (itemsets being a prominent example).
 	 */
-	getSubscribableDependenciesByReference(reference: string): readonly SubscribableDependency[];
+	readonly contextNode: EngineXPathNode;
 }

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

@@ -1,7 +1,14 @@
-import type { EngineConfig } from '../../client/EngineConfig.ts';
+import type { MissingResourceBehavior } from '../../client/constants.ts';
+import type { OpaqueReactiveObjectFactory } from '../../client/OpaqueReactiveObjectFactory.ts';
+import type { FetchFormAttachment, FetchResource } from '../../client/resources.ts';
 import type { CreateUniqueId } from '../../lib/unique-id.ts';
 
-export interface InstanceConfig extends Required<EngineConfig> {
+export interface InstanceConfig {
+	readonly stateFactory: OpaqueReactiveObjectFactory;
+	readonly fetchFormDefinition: FetchResource;
+	readonly fetchFormAttachment: FetchFormAttachment;
+	readonly missingResourceBehavior: MissingResourceBehavior;
+
 	/**
 	 * Uniqueness per form instance session (so e.g. persistence isn't necessary).
 	 */

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

@@ -0,0 +1,24 @@
+import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
+import type { BindComputationExpression } from '../../parse/expression/BindComputationExpression.ts';
+import type { EvaluationContext } from './EvaluationContext.ts';
+
+export type DecodeInstanceValue = (value: string) => string;
+
+interface InstanceValueContextDefinitionBind {
+	readonly calculate: BindComputationExpression<'calculate'> | null;
+	readonly readonly: BindComputationExpression<'readonly'>;
+}
+
+export interface InstanceValueContextDefinition {
+	readonly bind: InstanceValueContextDefinitionBind;
+	readonly defaultValue: string;
+}
+
+export interface InstanceValueContext extends EvaluationContext {
+	readonly scope: ReactiveScope;
+	readonly definition: InstanceValueContextDefinition;
+	readonly decodeInstanceValue: DecodeInstanceValue;
+
+	isReadonly(): boolean;
+	isRelevant(): boolean;
+}

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

@@ -0,0 +1,53 @@
+import type { FormLanguage } from '../../client/FormLanguage.ts';
+import type { RootNode, RootNodeState } from '../../client/RootNode.ts';
+
+export interface PrimaryInstanceDocumentState
+	extends Omit<
+		RootNodeState,
+		// Allow for override with `RootNode`, which is not presently considered a
+		// child node in the client API
+		'children'
+	> {
+	/**
+	 * @todo while this is an internal interface, this feels like maybe an
+	 * unnecessary indirection? It would probably be fine for it to reference
+	 * `Root` directly? We do get some minor benefit from making sure the client
+	 * and internal types are aligned, but we also already enforce that by
+	 * ensuring `Root implements RootNode`...
+	 */
+	get children(): readonly RootNode[];
+}
+
+/**
+ * Provides an interface most similar to what we would expose at the
+ * `@getodk/xforms-engine` package boundary, if we were to document the primary
+ * instance document's types for a client.
+ *
+ * Note: this interface (as well as {@link currentState}'s {@link PrimaryInstanceDocumentState}) is derived from {@link RootNode} to help avoid drift if that underlying interface (or its shared {@link BaseNode} interface) is updated.
+ *
+ */
+export interface PrimaryInstanceDocument
+	extends Omit<
+		RootNode,
+		// prettier-ignore
+		// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+		| 'nodeType' // Allow for override with 'primary-instance'
+		| 'currentState' // Allow for override of `children`
+		| 'setLanguage' // Allow for override of return type
+	> {
+	readonly nodeType: 'primary-instance';
+	readonly currentState: PrimaryInstanceDocumentState;
+
+	/**
+	 * @todo This intentionally returns `unknown` as a hint that we will likely
+	 * want to move away from returning {@link RootNode} (i.e. "all of the state",
+	 * as it was conceived in that design effort) on every state change.
+	 *
+	 * In this case, it may be sensible to return any of:
+	 *
+	 * - Just the state set directly (i.e. the input {@link FormLanguage})
+	 * - That effective state, and some representation of all affected nodes
+	 * - Something less obvious, but potentially more useful to clients?
+	 */
+	setLanguage(language: FormLanguage): unknown;
+}

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

@@ -1,5 +1,6 @@
-import type { ActiveLanguage } from '../../index.ts';
+import type { Accessor } from 'solid-js';
+import type { ActiveLanguage } from '../../client/FormLanguage.ts';
 
 export interface TranslationContext {
-	get activeLanguage(): ActiveLanguage;
+	readonly getActiveLanguage: Accessor<ActiveLanguage>;
 }

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

@@ -1,9 +1,8 @@
+import type { FormNodeID } from '../../client/identity.ts';
 import type { AnyViolation } from '../../client/validation.ts';
 import type { BindComputationExpression } from '../../parse/expression/BindComputationExpression.ts';
 import type { MessageDefinition } from '../../parse/text/MessageDefinition.ts';
-import type { NodeID } from '../identity.ts';
 import type { EvaluationContext } from './EvaluationContext.ts';
-import type { SubscribableDependency } from './SubscribableDependency.ts';
 
 interface ValidationContextCurrentState {
 	get reference(): string;
@@ -20,8 +19,8 @@ interface ValidationContextDefinition {
 	readonly bind: ValidationContextDefinitionBind;
 }
 
-export interface ValidationContext extends EvaluationContext, SubscribableDependency {
-	readonly nodeId: NodeID;
+export interface ValidationContext extends EvaluationContext {
+	readonly nodeId: FormNodeID;
 	readonly definition: ValidationContextDefinition;
 	readonly currentState: ValidationContextCurrentState;
 

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

@@ -1,3 +1,4 @@
+import type { EngineXPathNode } from '../../integration/xpath/adapter/kind.ts';
 import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
 import type { BindComputationExpression } from '../../parse/expression/BindComputationExpression.ts';
 import type { EvaluationContext } from './EvaluationContext.ts';
@@ -17,7 +18,7 @@ export interface ValueContextDefinition {
 export interface ValueContext<RuntimeValue> extends EvaluationContext {
 	readonly scope: ReactiveScope;
 	readonly definition: ValueContextDefinition;
-	readonly contextNode: Element;
+	readonly contextNode: EngineXPathNode & this;
 
 	isReadonly(): boolean;
 	isRelevant(): boolean;

package/src/instance/internal-api/submission/ClientReactiveSubmittableInstance.ts

@@ -0,0 +1,20 @@
+import type { SubmissionDefinition } from '../../../client/submission/SubmissionDefinition.ts';
+import type { AncestorNodeValidationState } from '../../../client/validation.ts';
+import type { Root } from '../../Root.ts';
+import type {
+	ClientReactiveSubmittableParentNode,
+	ClientReactiveSubmittableParentNodeDefinition,
+} from './ClientReactiveSubmittableParentNode.ts';
+
+interface ClientReactiveSubmittableInstanceDefinition
+	extends ClientReactiveSubmittableParentNodeDefinition {
+	readonly submission: SubmissionDefinition;
+}
+
+export interface ClientReactiveSubmittableInstance
+	extends ClientReactiveSubmittableParentNode<Root> {
+	readonly definition: ClientReactiveSubmittableInstanceDefinition;
+	readonly root: Root;
+	readonly parent: null;
+	readonly validationState: AncestorNodeValidationState;
+}