@getodk/xforms-engine 0.1.1 → 0.3.0

package/src/body/group/BaseGroupDefinition.ts

@@ -1,14 +1,16 @@
 import { UpsertableMap } from '@getodk/common/lib/collections/UpsertableMap.ts';
-import type { XFormDOM } from '../../XFormDOM.ts';
 import type { XFormDefinition } from '../../XFormDefinition.ts';
-import { getLabelElement, getRepeatElement } from '../../lib/dom/query.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,
 	type BodyElementParentContext,
 } from '../BodyDefinition.ts';
 import { BodyElementDefinition } from '../BodyElementDefinition.ts';
-import { LabelDefinition } from '../text/LabelDefinition.ts';
+import type { StructureElementAppearanceDefinition } from '../appearance/structureElementAppearanceParser.ts';
+import { structureElementAppearanceParser } from '../appearance/structureElementAppearanceParser.ts';
 
 /**
  * These type names are derived from **and expand upon** the language used in
@@ -23,10 +25,6 @@ import { LabelDefinition } from '../text/LabelDefinition.ts';
  * - `presentation-group` is a group with a `<label>` child; its usage here
  *   differs from the spec language in that `presentation-group` does **not**
  *   have a `ref`
- * - `repeat-group` is not mentioned by the spec; it is an extension of
- *   `logical-group`, wherein its `ref` is the same as its immediate `<repeat>`
- *   child's `nodeset` (usage of each attribute is normalized during
- *   initialization, in {@link XFormDOM})
  * - `structural-group` is any `<group>` element which does not satisfy any of
  *   the other usage scenarios; this isn't exactly the terminology used, but is
  *   the most closely fitting name for the concept where the other sceanarios
@@ -34,20 +32,17 @@ import { LabelDefinition } from '../text/LabelDefinition.ts';
  *
  * A more succinct decision tree:
  *
- * - `<group ref="$ref"><repeat nodeset="$ref">` -> `repeat-group`, else
  * - `<group ref="$ref">` -> `logical-group`, else
  * - `<group><label>` -> `presentation-group`, else
  * - `<group>` -> `structural-group`
  */
-export type GroupType =
-	| 'logical-group'
-	| 'presentation-group'
-	| 'repeat-group'
-	| 'structural-group';
+export type GroupType = 'logical-group' | 'presentation-group' | 'structural-group';
 
 export abstract class BaseGroupDefinition<
 	Type extends GroupType,
 > extends BodyElementDefinition<Type> {
+	// TODO: does this really accomplish anything? It seems highly unlikely it
+	// has enough performance benefit to outweigh its memory and lookup costs.
 	private static groupTypes = new UpsertableMap<Element, GroupType | null>();
 
 	protected static getGroupType(localName: string, element: Element): GroupType | null {
@@ -56,20 +51,8 @@ export abstract class BaseGroupDefinition<
 				return null;
 			}
 
-			const ref = element.getAttribute('ref');
-
-			if (ref != null) {
-				const repeat = getRepeatElement(element);
-
-				if (repeat == null) {
-					return 'logical-group';
-				}
-
-				if (repeat.getAttribute('nodeset') === ref) {
-					return 'repeat-group';
-				}
-
-				throw new Error('Unexpected <repeat> child of unrelated <group>');
+			if (element.hasAttribute('ref')) {
+				return 'logical-group';
 			}
 
 			const label = getLabelElement(element);
@@ -87,6 +70,7 @@ export abstract class BaseGroupDefinition<
 	readonly children: BodyElementDefinitionArray;
 
 	override readonly reference: string | null;
+	readonly appearances: StructureElementAppearanceDefinition;
 	override readonly label: LabelDefinition | null;
 
 	constructor(
@@ -98,7 +82,8 @@ 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);
 	}
 
@@ -107,31 +92,9 @@ export abstract class BaseGroupDefinition<
 		const children = Array.from(element.children).filter((child) => {
 			const childName = child.localName;
 
-			return childName !== 'label' && childName !== 'repeat';
+			return childName !== 'label';
 		});
 
 		return BodyDefinition.getChildElementDefinitions(form, this, element, children);
 	}
 }
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export const repeatGroup = <T extends BaseGroupDefinition<any>>(
-	groupDefinition: T
-): Extract<T, BaseGroupDefinition<'repeat-group'>> | null => {
-	if (groupDefinition.type === 'repeat-group') {
-		return groupDefinition as Extract<T, BaseGroupDefinition<'repeat-group'>>;
-	}
-
-	return null;
-};
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export const nonRepeatGroup = <T extends BaseGroupDefinition<any>>(
-	groupDefinition: T
-): Exclude<T, BaseGroupDefinition<'repeat-group'>> | null => {
-	if (groupDefinition.type === 'repeat-group') {
-		return null;
-	}
-
-	return groupDefinition as Exclude<T, BaseGroupDefinition<'repeat-group'>>;
-};

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

@@ -1,7 +1,14 @@
+import type { TokenListParser } from '../lib/TokenListParser.ts';
 import type { AnyNodeDefinition } from '../model/NodeDefinition.ts';
-import type { InstanceNodeType } from './node-types.js';
+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 {
 	/**
@@ -41,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;
 
 	/**
@@ -104,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;
 }
@@ -126,6 +147,12 @@ export interface BaseNode {
 	 */
 	readonly nodeId: FormNodeID;
 
+	/**
+	 * @see {@link TokenListParser} for details.
+	 */
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	readonly appearances: NodeAppearances<any> | null;
+
 	/**
 	 * Each node has a definition which specifies aspects of the node defined in
 	 * the form. These aspects include (but are not limited to) the node's data
@@ -173,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

@@ -1,8 +1,10 @@
-import type { NonRepeatGroupElementDefinition } from '../body/BodyDefinition.ts';
+import type { AnyGroupElementDefinition } from '../body/BodyDefinition.ts';
 import type { SubtreeDefinition } from '../model/SubtreeDefinition.ts';
 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;
@@ -14,9 +16,11 @@ export interface GroupNodeState extends BaseNodeState {
 // TODO: as with `SubtreeNode`'s `SubtreeDefinition`, there is a naming
 // inconsistency emerging here.
 export interface GroupDefinition extends SubtreeDefinition {
-	readonly bodyElement: NonRepeatGroupElementDefinition;
+	readonly bodyElement: AnyGroupElementDefinition;
 }
 
+export type GroupNodeAppearances = NodeAppearances<GroupDefinition>;
+
 /**
  * A node corresponding to an XForms `<group>`.
  */
@@ -26,8 +30,10 @@ export interface GroupDefinition extends SubtreeDefinition {
 // for context.
 export interface GroupNode extends BaseNode {
 	readonly nodeType: 'group';
+	readonly appearances: GroupNodeAppearances;
 	readonly definition: GroupDefinition;
 	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/NodeAppearances.ts

@@ -0,0 +1,22 @@
+import type { ParsedTokenList } from '../lib/TokenListParser.ts';
+import type { NodeDefinition } from '../model/NodeDefinition.ts';
+
+/**
+ * - Provides a means to distinguish between internal and client-facing names
+ *   for the same {@link ParsedTokenList} types.
+ *
+ * - Anticipates some iteration on both parsed ("definition") types and
+ *   client-facing node types, which may not happen in tandem.
+ */
+// prettier-ignore
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type NodeAppearances<Definition extends NodeDefinition<any>> =
+	Definition extends {
+		readonly bodyElement: {
+			readonly appearances:
+				// eslint-disable-next-line @typescript-eslint/no-explicit-any
+				infer Appearances extends ParsedTokenList<any>
+		};
+	}
+		? Appearances
+		: null;

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

@@ -1,7 +1,9 @@
+import type { BodyClassList } from '../body/BodyDefinition.ts';
 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 {
 	/**
@@ -21,10 +23,32 @@ export interface RootNodeState extends BaseNodeState {
 
 export interface RootNode extends BaseNode {
 	readonly nodeType: 'root';
+
+	/**
+	 * @todo this along with {@link classes} is... awkward.
+	 */
+	readonly appearances: null;
+
+	/**
+	 * @todo This is another odd deviation in {@link RootNode}. Unlike
+	 * {@link languages}, it doesn't feel particularly **essential**. While it
+	 * would deviate from XForms spec terminology, it seems like it _might be
+	 * reasonable_ to instead convey `<h:body class="...">` as
+	 * {@link RootNode.appearances} in the client interface. They do have slightly
+	 * different spec semantics (i.e. a body class can be anything, to trigger
+	 * styling in a form UI). But the **most likely anticipated** use case in Web
+	 * Forms would be the "pages" class, and perhaps "theme-grid". The former is
+	 * definitely conceptually similar to a XForms `appearance` (albeit
+	 * form-global, which is not a spec concept). The latter does as well, and we
+	 * already anticipate applying that concept in non-form-global ways.
+	 */
+	readonly classes: BodyClassList;
+
 	readonly definition: RootDefinition;
 	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,14 +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 {
@@ -34,16 +36,20 @@ export interface SelectNodeState extends BaseNodeState {
 	get value(): readonly SelectItem[];
 }
 
-export interface SelectDefinition extends ValueNodeDefinition {
+export interface SelectDefinition extends LeafNodeDefinition {
 	readonly bodyElement: AnySelectDefinition;
 }
 
+export type SelectNodeAppearances = NodeAppearances<SelectDefinition>;
+
 export interface SelectNode extends BaseNode {
 	readonly nodeType: 'select';
+	readonly appearances: SelectNodeAppearances;
 	readonly definition: SelectDefinition;
 	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,8 +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;
@@ -17,10 +19,12 @@ 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>;
+
 /**
  * A node which can be assigned a string/text value. A string node **MAY**
  * correspond to form field defined as an XForms `<input>`, which a user-facing
@@ -30,10 +34,12 @@ export interface StringDefinition extends ValueNodeDefinition {
  */
 export interface StringNode extends BaseNode {
 	readonly nodeType: 'string';
+	readonly appearances: StringNodeAppearances;
 	readonly definition: StringDefinition;
 	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;
@@ -50,8 +51,10 @@ export interface SubtreeDefinition extends BaseSubtreeDefinition {
 // TODO: directly test presentation of non-group subtree children/descendants
 export interface SubtreeNode extends BaseNode {
 	readonly nodeType: 'subtree';
+	readonly appearances: null;
 	readonly definition: SubtreeDefinition;
 	readonly root: RootNode;
 	readonly parent: GeneralParentNode;
 	readonly currentState: SubtreeNodeState;
+	readonly validationState: AncestorNodeValidationState;
 }