@getodk/xforms-engine 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getodk/xforms-engine",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "Apache-2.0",
   "description": "XForms engine for ODK Web Forms",
   "type": "module",
@@ -29,8 +29,8 @@
     "README.md"
   ],
   "engines": {
-    "node": "^18.20.3 || ^20.13.1 || ^22.2.0",
-    "yarn": "1.22.19"
+    "node": "^18.20.4 || ^20.15.1 || ^22.4.1",
+    "yarn": "1.22.22"
   },
   "scripts": {
     "build": "npm-run-all -nl build:*",
@@ -54,26 +54,25 @@
     "test:types": "tsc --project ./tsconfig.json --emitDeclarationOnly false --noEmit"
   },
   "dependencies": {
-    "solid-js": "^1.8.17"
+    "solid-js": "^1.8.18"
   },
   "devDependencies": {
-    "@babel/core": "^7.24.6",
-    "@getodk/tree-sitter-xpath": "0.1.1",
-    "@getodk/xpath": "0.1.2",
-    "@playwright/test": "^1.44.1",
-    "@vitest/browser": "^1.6.0",
+    "@babel/core": "^7.24.8",
+    "@getodk/tree-sitter-xpath": "0.1.2",
+    "@getodk/xpath": "0.2.0",
+    "@playwright/test": "^1.45.1",
+    "@vitest/browser": "^2.0.2",
     "babel-plugin-transform-jsbi-to-bigint": "^1.4.0",
     "http-server": "^14.1.1",
-    "jsdom": "^24.0.0",
-    "typedoc": "^0.25.13",
-    "unplugin-fonts": "^1.1.1",
-    "vite": "^5.2.11",
+    "jsdom": "^24.1.0",
+    "typedoc": "^0.26.4",
+    "vite": "^5.3.3",
     "vite-plugin-dts": "^3.9.1",
     "vite-plugin-no-bundle": "^4.0.0",
-    "vitest": "^1.6.0"
+    "vitest": "^2.0.2"
   },
   "peerDependencies": {
-    "solid-js": "^1.8.17"
+    "solid-js": "^1.8.18"
   },
   "peerDependenciesMeta": {
     "solid-js": {

package/src/body/BodyElementDefinition.ts

@@ -1,8 +1,9 @@
 import type { XFormDefinition } from '../XFormDefinition.ts';
 import { DependencyContext } from '../expression/DependencyContext.ts';
+import type { HintDefinition } from '../parse/text/HintDefinition.ts';
+import type { ItemLabelDefinition } from '../parse/text/ItemLabelDefinition.ts';
+import type { LabelDefinition } from '../parse/text/LabelDefinition.ts';
 import type { BodyElementParentContext } from './BodyDefinition.ts';
-import type { HintDefinition } from './text/HintDefinition.ts';
-import type { LabelDefinition } from './text/LabelDefinition.ts';
 
 /**
  * These category names roughly correspond to each of the ODK XForms spec's
@@ -22,7 +23,7 @@ export abstract class BodyElementDefinition<Type extends string> extends Depende
 	abstract readonly category: BodyElementCategory;
 	abstract readonly type: Type;
 	readonly hint: HintDefinition | null = null;
-	readonly label: LabelDefinition | null = null;
+	readonly label: ItemLabelDefinition | LabelDefinition | null = null;
 
 	readonly reference: string | null = null;
 	readonly parentReference: string | null;

package/src/body/RepeatElementDefinition.ts

@@ -1,11 +1,12 @@
 import { JAVAROSA_NAMESPACE_URI } from '@getodk/common/constants/xmlns.ts';
 import type { XFormDefinition } from '../XFormDefinition.ts';
+import { LabelDefinition } from '../parse/text/LabelDefinition.ts';
+import { parseNodesetReference } from '../parse/xpath/reference-parsing.ts';
 import type { BodyElementDefinitionArray, BodyElementParentContext } from './BodyDefinition.ts';
 import { BodyDefinition } from './BodyDefinition.ts';
 import { BodyElementDefinition } from './BodyElementDefinition.ts';
 import type { StructureElementAppearanceDefinition } from './appearance/structureElementAppearanceParser.ts';
 import { structureElementAppearanceParser } from './appearance/structureElementAppearanceParser.ts';
-import { LabelDefinition } from './text/LabelDefinition.ts';
 
 export class RepeatElementDefinition extends BodyElementDefinition<'repeat'> {
 	static override isCompatible(localName: string): boolean {
@@ -18,11 +19,8 @@ export class RepeatElementDefinition extends BodyElementDefinition<'repeat'> {
 	readonly appearances: StructureElementAppearanceDefinition;
 	override readonly label: LabelDefinition | null;
 
-	// TODO: this will fall into the growing category of non-`BindExpression`
-	// cases which have roughly the same design story.
 	readonly countExpression: string | null;
-
-	readonly isFixedCount: boolean;
+	readonly noAddRemoveExpression: string | null;
 
 	readonly children: BodyElementDefinitionArray;
 
@@ -31,7 +29,7 @@ export class RepeatElementDefinition extends BodyElementDefinition<'repeat'> {
 
 		this.label = LabelDefinition.forRepeatGroup(form, this);
 
-		const reference = element.getAttribute('nodeset');
+		const reference = parseNodesetReference(parent, element, 'nodeset');
 
 		if (reference == null) {
 			throw new Error('Invalid repeat: missing `nodeset` reference');
@@ -40,6 +38,7 @@ export class RepeatElementDefinition extends BodyElementDefinition<'repeat'> {
 		this.reference = reference;
 		this.appearances = structureElementAppearanceParser.parseFrom(element, 'appearance');
 		this.countExpression = element.getAttributeNS(JAVAROSA_NAMESPACE_URI, 'count');
+		this.noAddRemoveExpression = element.getAttributeNS(JAVAROSA_NAMESPACE_URI, 'noAddRemove');
 
 		const childElements = Array.from(element.children).filter((childElement) => {
 			const { localName } = childElement;
@@ -49,17 +48,6 @@ export class RepeatElementDefinition extends BodyElementDefinition<'repeat'> {
 		const children = BodyDefinition.getChildElementDefinitions(form, this, element, childElements);
 
 		this.children = children;
-
-		// Spec says this can be either `true()` or `false()`. That said, it
-		// could also presumably be `true ( )` or whatever.
-		const noAddRemove =
-			element
-				.getAttributeNS(JAVAROSA_NAMESPACE_URI, 'noAddRemove')
-				?.trim()
-				.replaceAll(/\s+/g, '') ?? 'false()';
-
-		// TODO: **probably** safe to disregard anything else?
-		this.isFixedCount = noAddRemove === 'true()';
 	}
 
 	override toJSON() {

package/src/body/control/ControlDefinition.ts

@@ -1,9 +1,10 @@
 import type { XFormDefinition } from '../../XFormDefinition.ts';
 import type { ParsedTokenList } from '../../lib/TokenListParser.ts';
+import { HintDefinition } from '../../parse/text/HintDefinition.ts';
+import { LabelDefinition } from '../../parse/text/LabelDefinition.ts';
+import { parseNodesetReference } from '../../parse/xpath/reference-parsing.ts';
 import type { BodyElementParentContext } from '../BodyDefinition.ts';
 import { BodyElementDefinition } from '../BodyElementDefinition.ts';
-import { HintDefinition } from '../text/HintDefinition.ts';
-import { LabelDefinition } from '../text/LabelDefinition.ts';
 
 // prettier-ignore
 type ControlType =
@@ -30,7 +31,7 @@ export abstract class ControlDefinition<
 	constructor(form: XFormDefinition, parent: BodyElementParentContext, element: Element) {
 		super(form, parent, element);
 
-		const reference = element.getAttribute('ref');
+		const reference = parseNodesetReference(parent, element, 'ref');
 
 		if (reference == null) {
 			throw new Error(`Invalid control: missing ref attribute`);

package/src/body/control/select/ItemDefinition.ts

@@ -1,14 +1,14 @@
 import { getValueElement, type ItemElement } from '../../../lib/dom/query.ts';
+import { ItemLabelDefinition } from '../../../parse/text/ItemLabelDefinition.ts';
 import type { XFormDefinition } from '../../../XFormDefinition.ts';
 import { BodyElementDefinition } from '../../BodyElementDefinition.ts';
-import { LabelDefinition } from '../../text/LabelDefinition.ts';
 import type { AnySelectDefinition } from './SelectDefinition.ts';
 
 export class ItemDefinition extends BodyElementDefinition<'item'> {
 	override readonly category = 'support';
 	override readonly type = 'item';
 
-	override readonly label: LabelDefinition | null;
+	override readonly label: ItemLabelDefinition | null;
 	readonly value: string;
 
 	constructor(
@@ -25,7 +25,7 @@ export class ItemDefinition extends BodyElementDefinition<'item'> {
 
 		super(form, parent, element);
 
-		this.label = LabelDefinition.forItem(form, this);
+		this.label = ItemLabelDefinition.from(form, this);
 		this.value = value;
 	}
 }

package/src/body/control/select/ItemsetDefinition.ts

@@ -1,7 +1,8 @@
-import { getValueElement, type ItemsetElement } from '../../../lib/dom/query.ts';
 import type { XFormDefinition } from '../../../XFormDefinition.ts';
+import { getValueElement, type ItemsetElement } from '../../../lib/dom/query.ts';
+import { ItemsetLabelDefinition } from '../../../parse/text/ItemsetLabelDefinition.ts';
+import { parseNodesetReference } from '../../../parse/xpath/reference-parsing.ts';
 import { BodyElementDefinition } from '../../BodyElementDefinition.ts';
-import { LabelDefinition } from '../../text/LabelDefinition.ts';
 import { ItemsetNodesetExpression } from './ItemsetNodesetExpression.ts';
 import { ItemsetValueExpression } from './ItemsetValueExpression.ts';
 import type { AnySelectDefinition } from './SelectDefinition.ts';
@@ -11,26 +12,42 @@ export class ItemsetDefinition extends BodyElementDefinition<'itemset'> {
 	readonly type = 'itemset';
 
 	override readonly reference: string;
-	override readonly label: LabelDefinition | null;
+	override readonly label: ItemsetLabelDefinition | null;
 
 	readonly nodes: ItemsetNodesetExpression;
 	readonly value: ItemsetValueExpression;
 
-	constructor(form: XFormDefinition, select: AnySelectDefinition, element: ItemsetElement) {
+	constructor(
+		form: XFormDefinition,
+		override readonly parent: AnySelectDefinition,
+		element: ItemsetElement
+	) {
+		super(form, parent, element);
+
+		const nodesetExpression = parseNodesetReference(parent, element, 'nodeset');
+
+		this.nodes = new ItemsetNodesetExpression(this, nodesetExpression);
+		this.reference = nodesetExpression;
+
 		const valueElement = getValueElement(element);
-		const valueExpression = valueElement?.getAttribute('ref');
 
-		if (valueExpression == null) {
-			throw new Error(`<itemset> has no <value>`);
+		if (valueElement == null) {
+			throw new Error('<itemset> has no <value>');
 		}
 
-		super(form, select, element);
+		const valueExpression = parseNodesetReference(
+			{
+				reference: null,
+			},
+			valueElement,
+			'ref'
+		);
 
-		const nodesetExpression = element.getAttribute('nodeset');
+		if (valueExpression == null) {
+			throw new Error(`<itemset> has no <value>`);
+		}
 
-		this.reference = nodesetExpression;
-		this.nodes = new ItemsetNodesetExpression(this, nodesetExpression);
 		this.value = new ItemsetValueExpression(this, valueExpression);
-		this.label = LabelDefinition.forItemset(form, this);
+		this.label = ItemsetLabelDefinition.from(form, this);
 	}
 }

package/src/body/control/select/ItemsetNodesetExpression.ts

@@ -3,6 +3,6 @@ import type { ItemsetDefinition } from './ItemsetDefinition.ts';
 
 export class ItemsetNodesetExpression extends DependentExpression<'nodes'> {
 	constructor(itemset: ItemsetDefinition, nodesetExpression: string) {
-		super(itemset, 'nodes', nodesetExpression);
+		super(itemset.parent, 'nodes', nodesetExpression);
 	}
 }

package/src/body/group/BaseGroupDefinition.ts

@@ -1,6 +1,8 @@
 import { UpsertableMap } from '@getodk/common/lib/collections/UpsertableMap.ts';
 import type { XFormDefinition } from '../../XFormDefinition.ts';
 import { getLabelElement } from '../../lib/dom/query.ts';
+import { LabelDefinition } from '../../parse/text/LabelDefinition.ts';
+import { parseNodesetReference } from '../../parse/xpath/reference-parsing.ts';
 import {
 	BodyDefinition,
 	type BodyElementDefinitionArray,
@@ -9,7 +11,6 @@ import {
 import { BodyElementDefinition } from '../BodyElementDefinition.ts';
 import type { StructureElementAppearanceDefinition } from '../appearance/structureElementAppearanceParser.ts';
 import { structureElementAppearanceParser } from '../appearance/structureElementAppearanceParser.ts';
-import { LabelDefinition } from '../text/LabelDefinition.ts';
 
 /**
  * These type names are derived from **and expand upon** the language used in
@@ -81,7 +82,7 @@ export abstract class BaseGroupDefinition<
 		super(form, parent, element);
 
 		this.children = children ?? this.getChildren(element);
-		this.reference = element.getAttribute('ref');
+		this.reference = parseNodesetReference(parent, element, 'ref');
 		this.appearances = structureElementAppearanceParser.parseFrom(element, 'appearance');
 		this.label = LabelDefinition.forGroup(form, this);
 	}

package/src/body/group/PresentationGroupDefinition.ts

@@ -1,6 +1,6 @@
 import type { XFormDefinition } from '../../XFormDefinition.ts';
+import { LabelDefinition } from '../../parse/text/LabelDefinition.ts';
 import type { BodyElementParentContext } from '../BodyDefinition.ts';
-import { LabelDefinition } from '../text/LabelDefinition.ts';
 import { BaseGroupDefinition } from './BaseGroupDefinition.ts';
 
 export class PresentationGroupDefinition extends BaseGroupDefinition<'presentation-group'> {

package/src/client/BaseNode.ts

@@ -4,6 +4,11 @@ import type { NodeAppearances } from './NodeAppearances.ts';
 import type { OpaqueReactiveObjectFactory } from './OpaqueReactiveObjectFactory.ts';
 import type { TextRange } from './TextRange.ts';
 import type { InstanceNodeType } from './node-types.ts';
+import type {
+	AncestorNodeValidationState,
+	LeafNodeValidationState,
+	NodeValidationState,
+} from './validation.ts';
 
 export interface BaseNodeState {
 	/**
@@ -43,11 +48,17 @@ export interface BaseNodeState {
 	 */
 	get relevant(): boolean;
 
-	// Note: according to spec, `required` is NOT inherited from ancestor nodes.
-	// What this means for a `required` state on subtree nodes is an open
-	// question. It was also raised on the first engine-internals iteration, and I
-	// could have sworn it was discussed in that PR, but finding any record of
-	// this discussion has proven elusive.
+	/**
+	 * Specifies whether the node must have a non-blank value to be valid (see
+	 * {@link value} for details).
+	 *
+	 * @see {@link https://getodk.github.io/xforms-spec/#bind-attributes}
+	 *
+	 * @default false
+	 *
+	 * @todo What is the expected behavior of `required` expressions defined for
+	 * non-leaf/value nodes?
+	 */
 	get required(): boolean;
 
 	/**
@@ -106,6 +117,14 @@ export interface BaseNodeState {
 	 *
 	 * Parent nodes, i.e. nodes which can contain {@link children}, do not store a
 	 * value state. For those nodes, their value state should always be `null`.
+	 *
+	 * A node's value is considered "blank" when its primary instance state is an
+	 * empty string, and it is considered "non-blank" otherwise. The engine may
+	 * represent node values according to aspects of the node's definition (such
+	 * as its defined data type, its associated control type if any). The node's
+	 * value being blank or non-blank may contribute to satisfying conditions of
+	 * the node's validity ({@link constraint}, {@link required}). Otherwise, it
+	 * is an internal engine consideration.
 	 */
 	get value(): unknown;
 }
@@ -181,8 +200,55 @@ export interface BaseNode {
 	readonly parent: BaseNode | null;
 
 	/**
-	 * Each node provides a discrete object representing the stateful aspects of
-	 * that node which will change over time. When a client provides a {@link OpaqueReactiveObjectFactory}
+	 * Each node provides a discrete object representing the stateful aspects\* of
+	 * that node which will change over time. When a client provides a
+	 * {@link OpaqueReactiveObjectFactory}, the engine will update the properties
+	 * of this object as their respective states change, so a client can implement
+	 * reactive updates that respond to changes as they occur.
+	 *
+	 * \* This includes state which is either client-/user-mutable, or state which
+	 *    is computed based on the core XForms computation model. Each node also
+	 *    exposes {@link validationState}, which reflects the validity of the
+	 *    node, or its descendants.
 	 */
 	readonly currentState: BaseNodeState;
+
+	/**
+	 * Represents the validation state of a the node itself, or its descendants.
+	 *
+	 * @see {@link AncestorNodeValidationState} and
+	 * {@link LeafNodeValidationState} for additional details.
+	 *
+	 * While filling a form (i.e. prior to submission), validation state can be
+	 * viewed as computed metadata about the form state. The validation conditions
+	 * and their violation messages produced by a node _may be computed on
+	 * demand_. Clients should assume:
+	 *
+	 * 1. Validation state **will be current** when directly read by the client.
+	 *    Accessing validation state _may_ invoke engine computation of that state
+	 *    _at that time_.
+	 *
+	 *    It **may** also be pre-computed by the engine so that direct reads are
+	 *    less computationally expensive, but such optimizations cannot be
+	 *    guaranteed by the engine at this time.
+	 *
+	 * 2. For clients providing an {@link OpaqueReactiveObjectFactory}, accessing
+	 *    validation state within a reactive context **will produce updates** to
+	 *    the validation state, as long as the client retains a subscription to
+	 *    that state.
+	 *
+	 *    If it is possible to detect interruption of such client- reactive
+	 *    subscriptions, the engine _may defer computations_ until subsequent
+	 *    client read/re-subscription, in order to reduce unnecessary
+	 *    computational overhead. Again, such optimizations cannot be guaranteed
+	 *    by the engine at this time.
+	 *
+	 * @todo it's easier to conceive a reliable, general solution to optimizing
+	 * the direct read case, than it is for the client-reactive case (largely
+	 * because our solution for client reactivity is intentionally opaque). If it
+	 * turns out that such optimizations are crucial for overall usability, the
+	 * client-reactive case may best be served by additional APIs for reactive
+	 * clients to explicitly pause and resume recomputation.
+	 */
+	readonly validationState: NodeValidationState;
 }

package/src/client/GroupNode.ts

@@ -4,6 +4,7 @@ import type { BaseNode, BaseNodeState } from './BaseNode.ts';
 import type { NodeAppearances } from './NodeAppearances.ts';
 import type { RootNode } from './RootNode.ts';
 import type { GeneralChildNode, GeneralParentNode } from './hierarchy.ts';
+import type { AncestorNodeValidationState } from './validation.ts';
 
 export interface GroupNodeState extends BaseNodeState {
 	get hint(): null;
@@ -34,4 +35,5 @@ export interface GroupNode extends BaseNode {
 	readonly root: RootNode;
 	readonly parent: GeneralParentNode;
 	readonly currentState: GroupNodeState;
+	readonly validationState: AncestorNodeValidationState;
 }

package/src/client/ModelValueNode.ts

@@ -0,0 +1,40 @@
+import type { LeafNodeDefinition } from '../model/LeafNodeDefinition.ts';
+import type { BaseNode, BaseNodeState } from './BaseNode.ts';
+import type { GeneralParentNode } from './hierarchy.ts';
+import type { RootNode } from './RootNode.ts';
+import type { LeafNodeValidationState } from './validation.ts';
+
+export interface ModelValueNodeState extends BaseNodeState {
+	get label(): null;
+	get hint(): null;
+	get children(): null;
+	get valueOptions(): null;
+
+	/**
+	 * Reflects the current value of a {@link ModelValueNode}. This value may be
+	 * populated when a form is loaded, and it may be updated by certain
+	 * computations defined by the form.
+	 */
+	get value(): string;
+}
+
+export interface ModelValueDefinition extends LeafNodeDefinition {
+	readonly bodyElement: null;
+}
+
+/**
+ * A node which is:
+ *
+ * - model-only (i.e. it has no corresponding body element)
+ * - a leaf/value node (i.e. it has no element children; it may be defined in
+ *   the form's `<model>` as either an {@link Element} or {@link Attr})
+ */
+export interface ModelValueNode extends BaseNode {
+	readonly nodeType: 'model-value';
+	readonly appearances: null;
+	readonly definition: ModelValueDefinition;
+	readonly root: RootNode;
+	readonly parent: GeneralParentNode;
+	readonly currentState: ModelValueNodeState;
+	readonly validationState: LeafNodeValidationState;
+}

package/src/client/NoteNode.ts

@@ -0,0 +1,74 @@
+import type { InputDefinition } from '../body/control/InputDefinition.ts';
+import type { LeafNodeDefinition } from '../model/LeafNodeDefinition.ts';
+import type { BaseNode, BaseNodeState } from './BaseNode.ts';
+import type { GeneralParentNode } from './hierarchy.ts';
+import type { NodeAppearances } from './NodeAppearances.ts';
+import type { RootNode } from './RootNode.ts';
+import type { TextRange } from './TextRange.ts';
+import type { LeafNodeValidationState } from './validation.ts';
+
+export interface NoteNodeState extends BaseNodeState {
+	/**
+	 * Note-specific specialization: a note will always have a non-null value in
+	 * at least one of:
+	 *
+	 * - {@link label}
+	 * - {@link hint}
+	 *
+	 * This is an alias to whichever is present, with precedent to {@link label}
+	 * if both are present.
+	 */
+	// ^ @todo While it's possible to convey this at the type level, the resulting
+	// types would be far more complex than this, which is not ideal especially at
+	// the package (client) boundary. This alias is a concession that the simpler
+	// type is preferred, but that it is still important to convey to clients
+	// that at least one form-defined text value will always be available. Note:
+	// at least for a first pass, we won't guarantee that the resulting text is
+	// non-empty. (We'd probably need to accept an engine fallback to make that
+	// guarantee; otherwise we'd need to error on invalid state, potentially at
+	// arbitrary points in time.)
+	//
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	get noteText(): NonNullable<this['label'] | this['hint']>;
+
+	/**
+	 * A note will **always** be `readonly`.
+	 */
+	readonly readonly: true;
+
+	get label(): TextRange<'label', 'form'> | null;
+	get hint(): TextRange<'hint', 'form'> | null;
+	get children(): null;
+	get valueOptions(): null;
+
+	/**
+	 * Reflects the readonly value of a {@link NoteNode}, or `null` if blank.
+	 */
+	// Note that being nullable is an intentional deviation from most other value
+	// node types, specifically to make a clear distinction between blank and
+	// non-blank values (as that has been a primary driver for prioritizing note
+	// functionality).
+	get value(): string | null;
+}
+
+export interface NoteDefinition extends LeafNodeDefinition {
+	readonly bodyElement: InputDefinition;
+}
+
+export type NoteNodeAppearances = NodeAppearances<NoteDefinition>;
+
+/**
+ * A node which is:
+ *
+ * - associated with an input, with at least one text element (label or hint)
+ * - guaranteed to be {@link NoteNodeState.readonly | readonly}
+ */
+export interface NoteNode extends BaseNode {
+	readonly nodeType: 'note';
+	readonly appearances: NoteNodeAppearances;
+	readonly definition: NoteDefinition;
+	readonly root: RootNode;
+	readonly parent: GeneralParentNode;
+	readonly currentState: NoteNodeState;
+	readonly validationState: LeafNodeValidationState;
+}

package/src/client/README.md

@@ -20,6 +20,7 @@ The interface is designed to:
 - Facilitate loading any of a form's externally referenced resources, by means of a client-provided generic resource accessor[^2]
 
 [^1]: This factory **may be** reactive, and for many clients that is the anticipated usage. But no assumptions are made by the engine about reactivity or any other implementation details beyond the factory's type definition.
+
 [^2]: This accessor **may** access networked resources, and for many clients that is the anticipated usage. But no assumptions are made by the engine about the provenance of any resources it requests beyond the accessor's type definition.
 
 ### Non-goals

package/src/client/RootNode.ts

@@ -3,6 +3,7 @@ import type { RootDefinition } from '../model/RootDefinition.ts';
 import type { BaseNode, BaseNodeState } from './BaseNode.ts';
 import type { ActiveLanguage, FormLanguage, FormLanguages } from './FormLanguage.ts';
 import type { GeneralChildNode } from './hierarchy.ts';
+import type { AncestorNodeValidationState } from './validation.ts';
 
 export interface RootNodeState extends BaseNodeState {
 	/**
@@ -47,6 +48,7 @@ export interface RootNode extends BaseNode {
 	readonly root: RootNode;
 	readonly parent: null;
 	readonly currentState: RootNodeState;
+	readonly validationState: AncestorNodeValidationState;
 
 	/**
 	 * @todo as with {@link RootNodeState.activeLanguage}, this is the most

package/src/client/SelectNode.ts

@@ -1,15 +1,16 @@
 import type { AnySelectDefinition } from '../body/control/select/SelectDefinition.ts';
-import type { ValueNodeDefinition } from '../model/ValueNodeDefinition.ts';
+import type { LeafNodeDefinition } from '../model/LeafNodeDefinition.ts';
 import type { BaseNode, BaseNodeState } from './BaseNode.ts';
 import type { NodeAppearances } from './NodeAppearances.ts';
 import type { RootNode } from './RootNode.ts';
 import type { StringNode } from './StringNode.ts';
 import type { TextRange } from './TextRange.ts';
 import type { GeneralParentNode } from './hierarchy.ts';
+import type { LeafNodeValidationState } from './validation.ts';
 
 export interface SelectItem {
 	get value(): string;
-	get label(): TextRange<'label'> | null;
+	get label(): TextRange<'item-label'> | null;
 }
 
 export interface SelectNodeState extends BaseNodeState {
@@ -35,7 +36,7 @@ export interface SelectNodeState extends BaseNodeState {
 	get value(): readonly SelectItem[];
 }
 
-export interface SelectDefinition extends ValueNodeDefinition {
+export interface SelectDefinition extends LeafNodeDefinition {
 	readonly bodyElement: AnySelectDefinition;
 }
 
@@ -48,6 +49,7 @@ export interface SelectNode extends BaseNode {
 	readonly root: RootNode;
 	readonly parent: GeneralParentNode;
 	readonly currentState: SelectNodeState;
+	readonly validationState: LeafNodeValidationState;
 
 	/**
 	 * For use by a client to update the selection of a select node where:

package/src/client/StringNode.ts

@@ -1,9 +1,10 @@
 import type { InputDefinition } from '../body/control/InputDefinition.ts';
-import type { ValueNodeDefinition } from '../model/ValueNodeDefinition.ts';
+import type { LeafNodeDefinition } from '../model/LeafNodeDefinition.ts';
 import type { BaseNode, BaseNodeState } from './BaseNode.ts';
 import type { NodeAppearances } from './NodeAppearances.ts';
 import type { RootNode } from './RootNode.ts';
 import type { GeneralParentNode } from './hierarchy.ts';
+import type { LeafNodeValidationState } from './validation.ts';
 
 export interface StringNodeState extends BaseNodeState {
 	get children(): null;
@@ -18,8 +19,8 @@ export interface StringNodeState extends BaseNodeState {
 	get value(): string;
 }
 
-export interface StringDefinition extends ValueNodeDefinition {
-	readonly bodyElement: InputDefinition | null;
+export interface StringDefinition extends LeafNodeDefinition {
+	readonly bodyElement: InputDefinition;
 }
 
 export type StringNodeAppearances = NodeAppearances<StringDefinition>;
@@ -38,6 +39,7 @@ export interface StringNode extends BaseNode {
 	readonly root: RootNode;
 	readonly parent: GeneralParentNode;
 	readonly currentState: StringNodeState;
+	readonly validationState: LeafNodeValidationState;
 
 	/**
 	 * For use by a client to update the value of a string node.

package/src/client/SubtreeNode.ts

@@ -2,6 +2,7 @@ import type { SubtreeDefinition as BaseSubtreeDefinition } from '../model/Subtre
 import type { BaseNode, BaseNodeState } from './BaseNode.ts';
 import type { RootNode } from './RootNode.ts';
 import type { GeneralChildNode, GeneralParentNode } from './hierarchy.ts';
+import type { AncestorNodeValidationState } from './validation.ts';
 
 export interface SubtreeNodeState extends BaseNodeState {
 	get label(): null;
@@ -55,4 +56,5 @@ export interface SubtreeNode extends BaseNode {
 	readonly root: RootNode;
 	readonly parent: GeneralParentNode;
 	readonly currentState: SubtreeNodeState;
+	readonly validationState: AncestorNodeValidationState;
 }