@getodk/xforms-engine 0.2.0 → 0.4.0

package/src/client/hierarchy.ts

@@ -1,16 +1,52 @@
 import type { ExpandUnion } from '@getodk/common/types/helpers.d.ts';
 import type { GroupNode } from './GroupNode.ts';
-import type { RepeatInstanceNode } from './RepeatInstanceNode.ts';
-import type { RepeatRangeNode } from './RepeatRangeNode.ts';
+import type { ModelValueNode } from './ModelValueNode.ts';
+import type { NoteNode } from './NoteNode.ts';
+import type { RepeatInstanceNode } from './repeat/RepeatInstanceNode.ts';
+import type { RepeatRangeControlledNode } from './repeat/RepeatRangeControlledNode.ts';
+import type { RepeatRangeUncontrolledNode } from './repeat/RepeatRangeUncontrolledNode.ts';
 import type { RootNode } from './RootNode.ts';
 import type { SelectNode } from './SelectNode.ts';
 import type { StringNode } from './StringNode.ts';
 import type { SubtreeNode } from './SubtreeNode.ts';
+import type { TriggerNode } from './TriggerNode.ts';
+import type { RangeNode } from './unsupported/RangeNode.ts';
+import type { RankNode } from './unsupported/RankNode.ts';
+import type { UploadNode } from './unsupported/UploadNode.ts';
 
 // prettier-ignore
-export type AnyLeafNode =
+export type AnyUnsupportedControlNode =
+	| RangeNode
+	| RankNode
+	| UploadNode;
+
+// prettier-ignore
+export type AnyControlNode =
+	| NoteNode
 	| SelectNode
-	| StringNode;
+	| StringNode
+	| TriggerNode;
+
+// prettier-ignore
+export type AnyLeafNode =
+	| AnyControlNode
+	| AnyUnsupportedControlNode
+	| ModelValueNode;
+
+// prettier-ignore
+export type RepeatRangeNode =
+	| RepeatRangeControlledNode
+	| RepeatRangeUncontrolledNode;
+
+/**
+ * Any of the concrete node types which may be a parent of non-repeat instance
+ * child nodes.
+ */
+export type GeneralParentNode =
+	| RootNode // eslint-disable-line @typescript-eslint/sort-type-constituents
+	| SubtreeNode
+	| GroupNode
+	| RepeatInstanceNode;
 
 /**
  * Any of the concrete node types which may be a parent of any other node.
@@ -21,12 +57,10 @@ export type AnyLeafNode =
  * - Repeat instances should (continue to) specify {@link RepeatRangeNode}.
  * - All other child nodes should specify {@link GeneralParentNode}.
  */
+// prettier-ignore
 export type AnyParentNode =
-	| RootNode // eslint-disable-line @typescript-eslint/sort-type-constituents
-	| SubtreeNode
-	| GroupNode
-	| RepeatRangeNode
-	| RepeatInstanceNode;
+	| GeneralParentNode
+	| RepeatRangeNode;
 
 /**
  * Any of the concrete node types a client may get from the engine's form
@@ -38,12 +72,6 @@ export type AnyParentNode =
  */
 export type AnyNode = ExpandUnion<AnyLeafNode | AnyParentNode>;
 
-/**
- * Any of the concrete node types which may be a parent of non-repeat instance
- * child nodes.
- */
-export type GeneralParentNode = Exclude<AnyParentNode, RepeatRangeNode>;
-
 /**
  * Any of the concrete node types which may be a child of any other node.
  *

package/src/client/node-types.ts

@@ -1,10 +1,25 @@
+// prettier-ignore
+export type UnsupportedControlNodeType =
+	| 'range'
+	| 'rank'
+	| 'upload';
+
+// prettier-ignore
+export type RepeatRangeNodeType =
+	| 'repeat-range:controlled'
+	| 'repeat-range:uncontrolled'
+
 // prettier-ignore
 export type InstanceNodeType =
 	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
 	| 'root'
-	| 'repeat-range'
+	| RepeatRangeNodeType
 	| 'repeat-instance'
 	| 'group'
 	| 'subtree'
+	| 'model-value'
+	| 'note'
 	| 'select'
-	| 'string';
+	| 'string'
+	| 'trigger'
+	| UnsupportedControlNodeType;

package/src/client/{RepeatRangeNode.ts → repeat/BaseRepeatRangeNode.ts}

@@ -1,12 +1,14 @@
-import type { RepeatRangeDefinition } from '../model/RepeatRangeDefinition.ts';
-import type { BaseNode, BaseNodeState } from './BaseNode.ts';
-import type { NodeAppearances } from './NodeAppearances.ts';
+import type { AnyRepeatRangeDefinition } from '../../parse/model/RepeatRangeDefinition.ts';
+import type { BaseNode, BaseNodeState } from '../BaseNode.ts';
+import type { NodeAppearances } from '../NodeAppearances.ts';
+import type { RootNode } from '../RootNode.ts';
+import type { TextRange } from '../TextRange.ts';
+import type { GeneralParentNode } from '../hierarchy.ts';
+import type { RepeatRangeNodeType } from '../node-types.ts';
+import type { AncestorNodeValidationState } from '../validation.ts';
 import type { RepeatInstanceNode } from './RepeatInstanceNode.ts';
-import type { RootNode } from './RootNode.ts';
-import type { TextRange } from './TextRange.ts';
-import type { GeneralParentNode } from './hierarchy.ts';
 
-export interface RepeatRangeNodeState extends BaseNodeState {
+export interface BaseRepeatRangeNodeState extends BaseNodeState {
 	get hint(): null;
 	get label(): TextRange<'label'> | null;
 
@@ -16,7 +18,7 @@ export interface RepeatRangeNodeState extends BaseNodeState {
 	 * Note: the web-forms engine's representation of this structure differs from
 	 * the underlying XForms specification's primary instance structure.
 	 *
-	 * @see {@link RepeatRangeNode} for additional detail.
+	 * @see {@link BaseRepeatRangeNode} for additional detail.
 	 */
 	get children(): readonly RepeatInstanceNode[];
 
@@ -24,12 +26,12 @@ export interface RepeatRangeNodeState extends BaseNodeState {
 	get value(): null;
 }
 
-export type RepeatRangeNodeAppearances = NodeAppearances<RepeatRangeDefinition>;
+export type RepeatRangeNodeAppearances = NodeAppearances<AnyRepeatRangeDefinition>;
 
 /**
  * Represents a contiguous set of zero or more {@link RepeatInstanceNode}s
  * (accessed by its
- * {@link RepeatRangeNodeState.children | `currentState.children`}).
+ * {@link BaseRepeatRangeNodeState.children | `currentState.children`}).
  *
  * This structure is modeled as a node, like any other, in the web-forms engine
  * representation, which notably differs from the corresponding structure in the
@@ -88,17 +90,14 @@ export type RepeatRangeNodeAppearances = NodeAppearances<RepeatRangeDefinition>;
  * Importantly, if the state of a given repeat range has no instances, no aspect
  * of these repeats will be present in the underlying XForms primary instance
  * state, but the web-forms engine's representations **retains a reference** to
- * its {@link RepeatRangeNode}.
+ * its {@link BaseRepeatRangeNode}.
  */
-export interface RepeatRangeNode extends BaseNode {
-	readonly nodeType: 'repeat-range';
+export interface BaseRepeatRangeNode extends BaseNode {
+	readonly nodeType: RepeatRangeNodeType;
 	readonly appearances: RepeatRangeNodeAppearances;
-	readonly definition: RepeatRangeDefinition;
+	readonly definition: AnyRepeatRangeDefinition;
 	readonly root: RootNode;
 	readonly parent: GeneralParentNode;
-	readonly currentState: RepeatRangeNodeState;
-
-	addInstances(afterIndex?: number, count?: number): RootNode;
-
-	removeInstances(startIndex: number, count?: number): RootNode;
+	readonly currentState: BaseRepeatRangeNodeState;
+	readonly validationState: AncestorNodeValidationState;
 }

package/src/client/{RepeatInstanceNode.ts → repeat/RepeatInstanceNode.ts}

@@ -1,10 +1,11 @@
-import type { RepeatInstanceDefinition } from '../model/RepeatInstanceDefinition.ts';
-import type { RepeatTemplateDefinition } from '../model/RepeatTemplateDefinition.ts';
-import type { BaseNode, BaseNodeState } from './BaseNode.ts';
-import type { NodeAppearances } from './NodeAppearances.ts';
-import type { RepeatRangeNode } from './RepeatRangeNode.ts';
-import type { RootNode } from './RootNode.ts';
-import type { GeneralChildNode } from './hierarchy.ts';
+import type { RepeatInstanceDefinition } from '../../parse/model/RepeatInstanceDefinition.ts';
+import type { RepeatTemplateDefinition } from '../../parse/model/RepeatTemplateDefinition.ts';
+import type { BaseNode, BaseNodeState } from '../BaseNode.ts';
+import type { GeneralChildNode, RepeatRangeNode } from '../hierarchy.ts';
+import type { NodeAppearances } from '../NodeAppearances.ts';
+import type { RootNode } from '../RootNode.ts';
+import type { AncestorNodeValidationState } from '../validation.ts';
+import type { BaseRepeatRangeNode } from './BaseRepeatRangeNode.ts';
 
 export interface RepeatInstanceNodeState extends BaseNodeState {
 	// TODO(?): Previous iteration included an `index` getter here. I don't see it
@@ -37,9 +38,10 @@ export interface RepeatInstanceNode extends BaseNode {
 	 * Note: the web-forms engine's representation of this structure differs from
 	 * the underlying XForms specification's primary instance structure.
 	 *
-	 * @see {@link RepeatRangeNode} for additional detail.
+	 * @see {@link BaseRepeatRangeNode} for additional detail.
 	 */
 	readonly parent: RepeatRangeNode;
 
 	readonly currentState: RepeatInstanceNodeState;
+	readonly validationState: AncestorNodeValidationState;
 }

package/src/client/repeat/RepeatRangeControlledNode.ts

@@ -0,0 +1,20 @@
+import type { ControlledRepeatRangeDefinition } from '../../parse/model/RepeatRangeDefinition.ts';
+import type { BaseRepeatRangeNode, BaseRepeatRangeNodeState } from './BaseRepeatRangeNode.ts';
+import type { RepeatRangeUncontrolledNode } from './RepeatRangeUncontrolledNode.ts';
+
+/**
+ * {@inheritDoc BaseRepeatRangeNodeState}
+ * @see {@link BaseRepeatRangeNodeState}
+ */
+export interface RepeatRangeControlledState extends BaseRepeatRangeNodeState {}
+
+/**
+ * Represents a repeat range whose repeat instances are controlled by the
+ * engine, and cannot be added or removed by a client. Functionality and
+ * semantics are otherwise consistent with an [uncontrolled]
+ * {@link RepeatRangeUncontrolledNode}.
+ */
+export interface RepeatRangeControlledNode extends BaseRepeatRangeNode {
+	readonly nodeType: 'repeat-range:controlled';
+	readonly definition: ControlledRepeatRangeDefinition;
+}

package/src/client/repeat/RepeatRangeUncontrolledNode.ts

@@ -0,0 +1,21 @@
+import type { UncontrolledRepeatRangeDefinition } from '../../parse/model/RepeatRangeDefinition.ts';
+import type { RootNode } from '../RootNode.ts';
+import type { BaseRepeatRangeNode, BaseRepeatRangeNodeState } from './BaseRepeatRangeNode.ts';
+
+/**
+ * {@inheritDoc BaseRepeatRangeNodeState}
+ * @see {@link BaseRepeatRangeNodeState}
+ */
+export interface RepeatRangeUncontrolledState extends BaseRepeatRangeNodeState {}
+
+/**
+ * {@inheritDoc BaseRepeatRangeNode}
+ * @see {@link BaseRepeatRangeNode}
+ */
+export interface RepeatRangeUncontrolledNode extends BaseRepeatRangeNode {
+	readonly nodeType: 'repeat-range:uncontrolled';
+	readonly definition: UncontrolledRepeatRangeDefinition;
+
+	addInstances(afterIndex?: number, count?: number): RootNode;
+	removeInstances(startIndex: number, count?: number): RootNode;
+}

package/src/client/unsupported/RangeNode.ts

@@ -0,0 +1,14 @@
+import type { RangeControlDefinition } from '../../parse/body/control/RangeControlDefinition.ts';
+import type {
+	UnsupportedControlDefinition,
+	UnsupportedControlNode,
+} from './UnsupportedControlNode.ts';
+
+export interface RangeNodeDefinition extends UnsupportedControlDefinition {
+	readonly bodyElement: RangeControlDefinition;
+}
+
+export interface RangeNode extends UnsupportedControlNode {
+	readonly nodeType: 'range';
+	readonly definition: RangeNodeDefinition;
+}

package/src/client/unsupported/RankNode.ts

@@ -0,0 +1,14 @@
+import type { RankControlDefinition } from '../../parse/body/control/RankControlDefinition.ts';
+import type {
+	UnsupportedControlDefinition,
+	UnsupportedControlNode,
+} from './UnsupportedControlNode.ts';
+
+export interface RankNodeDefinition extends UnsupportedControlDefinition {
+	readonly bodyElement: RankControlDefinition;
+}
+
+export interface RankNode extends UnsupportedControlNode {
+	readonly nodeType: 'rank';
+	readonly definition: RankNodeDefinition;
+}

package/src/client/unsupported/UnsupportedControlNode.ts

@@ -0,0 +1,40 @@
+import type { UnknownAppearanceDefinition } from '../../parse/body/appearance/unknownAppearanceParser.ts';
+import type { RangeControlDefinition } from '../../parse/body/control/RangeControlDefinition.ts';
+import type { RankControlDefinition } from '../../parse/body/control/RankControlDefinition.ts';
+import type { UploadControlDefinition } from '../../parse/body/control/UploadControlDefinition.ts';
+import type { LeafNodeDefinition } from '../../parse/model/LeafNodeDefinition.ts';
+import type { BaseNode, BaseNodeState } from '../BaseNode.ts';
+import type { RootNode } from '../RootNode.ts';
+import type { GeneralParentNode } from '../hierarchy.ts';
+import type { UnsupportedControlNodeType } from '../node-types.ts';
+import type { LeafNodeValidationState } from '../validation.ts';
+
+export interface UnsupportedControlNodeState extends BaseNodeState {
+	get children(): null;
+	get valueOptions(): unknown;
+	get value(): unknown;
+}
+
+export type UnsupportedControlElementDefinition =
+	| RangeControlDefinition
+	| RankControlDefinition
+	| UploadControlDefinition;
+
+export interface UnsupportedControlDefinition extends LeafNodeDefinition {
+	readonly bodyElement: UnsupportedControlElementDefinition;
+}
+
+/**
+ * Stub node, for form controls pending further engine support.
+ */
+export interface UnsupportedControlNode extends BaseNode {
+	readonly nodeType: UnsupportedControlNodeType;
+	readonly appearances: UnknownAppearanceDefinition;
+	readonly definition: UnsupportedControlDefinition;
+	readonly root: RootNode;
+	readonly parent: GeneralParentNode;
+	readonly currentState: UnsupportedControlNodeState;
+	readonly validationState: LeafNodeValidationState;
+
+	setValue?(value: never): never;
+}

package/src/client/unsupported/UploadNode.ts

@@ -0,0 +1,14 @@
+import type { UploadControlDefinition } from '../../parse/body/control/UploadControlDefinition.ts';
+import type {
+	UnsupportedControlDefinition,
+	UnsupportedControlNode,
+} from './UnsupportedControlNode.ts';
+
+export interface UploadNodeDefinition extends UnsupportedControlDefinition {
+	readonly bodyElement: UploadControlDefinition;
+}
+
+export interface UploadNode extends UnsupportedControlNode {
+	readonly nodeType: 'upload';
+	readonly definition: UploadNodeDefinition;
+}

package/src/client/validation.ts

@@ -0,0 +1,199 @@
+import type { NodeID } from '../instance/identity.ts';
+import type { BaseNode, BaseNodeState } from './BaseNode.ts';
+import type { OpaqueReactiveObjectFactory } from './OpaqueReactiveObjectFactory.ts';
+import type { RootNode } from './RootNode.ts';
+import type { TextRange } from './TextRange.ts';
+
+// This interface exists so that extensions can share JSDoc for `valid`.
+interface BaseValidity {
+	/**
+	 * Specifies the unambiguous validity state for each validity condition of a
+	 * given node, or for the derived validity of any parent node whose descendants
+	 * are validated.
+	 *
+	 * For {@link ValidationCondition | form-defined conditions}, validity is
+	 * determined as follows:
+	 *
+	 *
+	 *   expression | state     |  blank  | non-blank
+	 * ------------:|:----------|:-------:|:---------:
+	 * `constraint` | `true`\*  | ✅      | ✅
+	 * `constraint` | `false`   | ✅      | ❌
+	 * `required`   | `false`\* | ✅      | ✅
+	 * `required`   | `true`    | ❌      | ✅
+	 *
+	 * - \* = default (expression not defined)
+	 * - ✅ = `valid: true`
+	 * - ❌ = `valid: false`
+	 */
+	readonly valid: boolean;
+}
+
+/**
+ * Form-defined conditions which determine node validity.
+ *
+ * @see {@link https://getodk.github.io/xforms-spec/#bind-attributes | `constraint` and `required` bind attributes}
+ */
+export type ValidationCondition = 'constraint' | 'required';
+
+interface ValidationConditionMessageRoles {
+	readonly constraint: 'constraintMsg';
+	readonly required: 'requiredMsg';
+}
+
+export type ValidationConditionMessageRole<Condition extends ValidationCondition> =
+	ValidationConditionMessageRoles[Condition];
+
+/**
+ * Source of a condition's violation message.
+ *
+ * - Form-defined messages (specified by the
+ *   {@link https://getodk.github.io/xforms-spec/#bind-attributes | `jr:constraintMsg` and `jr:requiredMsg`}
+ *   attributes) will be favored when provided by the form, and will be
+ *   translated according to the form's active language (where applicable).
+ *
+ * - Otherwise, an engine-defined message will be provided as a fallback. This
+ *   fallback is provided mainly for API consistency, and may be referenced for
+ *   testing purposes; user-facing clients are expected to provide fallback
+ *   messaging language most appropriate for their user neeeds. Engine-defined
+ *   fallback messages **are not translated**. They are intended to be used, if
+ *   at all, as sentinel values when a form-defined message is not available.
+ */
+// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+export type ViolationMessageSource = 'form' | 'engine';
+
+/**
+ * @see {@link ViolationMessage.asString}
+ */
+// prettier-ignore
+type ViolationMessageAsString<
+	Source extends ViolationMessageSource,
+	Condition extends ValidationCondition,
+> =
+	Source extends 'form'
+		? string
+		: `Condition not satisfied: ${Condition}`;
+
+/**
+ * A violation message is provided for every violation of a form-defined
+ * {@link ValidationCondition}.
+ */
+export interface ViolationMessage<
+	Condition extends ValidationCondition,
+	Source extends ViolationMessageSource = ViolationMessageSource,
+> extends TextRange<ValidationConditionMessageRole<Condition>> {
+	/**
+	 * - Form-defined violation messages may produce arbitrary text. This text may
+	 *   be translated
+	 *   ({@link https://getodk.github.io/xforms-spec/#fn:jr:itext | `jr:itext`}),
+	 *   and it may be dynamic (translations may reference form state with
+	 *   {@link https://getodk.github.io/xforms-spec/#body-elements | `<output>`}).
+	 *
+	 * - When a form-defined violation message is not available, an engine-defined
+	 *   message will be provided in its place. Engine-defined violation messages
+	 *   are statically defined (and therefore not presently translated by the
+	 *   engine). Their static value can also be referenced as a static type, by
+	 *   checking {@link isFallbackMessage}.
+	 */
+	get asString(): ViolationMessageAsString<Source, Condition>;
+}
+
+export interface ConditionSatisfied<Condition extends ValidationCondition> extends BaseValidity {
+	readonly condition: Condition;
+	readonly valid: true;
+	readonly message: null;
+}
+
+export interface ConditionViolation<Condition extends ValidationCondition> extends BaseValidity {
+	readonly condition: Condition;
+	readonly valid: false;
+	readonly message: ViolationMessage<Condition>;
+}
+
+export type ConditionValidation<Condition extends ValidationCondition> =
+	| ConditionSatisfied<Condition>
+	| ConditionViolation<Condition>;
+
+export type AnyViolation = ConditionViolation<ValidationCondition>;
+
+/**
+ * Represents the validation state of a leaf (or value) node.
+ *
+ * Validity is computed for two conditions:
+ *
+ * - {@link constraint}: arbitrary form-defined condition which specifies
+ *   whether a (non-blank) value is considered valid
+ *
+ *  - {@link required}: when a node is required, the node must have a non-blank
+ *    value to be considered valid
+ *
+ * Only one of these conditions can be violated (applicability is mutually
+ * exclusive). As such, {@link violation} provides a convenient way to determine
+ * whether a leaf/value node is valid with a single (null) check.
+ *
+ * @see {@link BaseValidity.valid} for additional details on how these
+ * conditions are evaluated (and how they interact with one another).
+ */
+export interface LeafNodeValidationState {
+	get constraint(): ConditionValidation<'constraint'>;
+	get required(): ConditionValidation<'required'>;
+
+	/**
+	 * Violations are mutually exclusive:
+	 *
+	 * - {@link constraint} can only be violated by a non-blank value
+	 * - {@link required} can only be violated by a blank value
+	 *
+	 * As such, at most one violation can be present. If none is present,
+	 * the node is considered valid.
+	 */
+	get violation(): AnyViolation | null;
+}
+
+/**
+ * Provides a reference to any leaf/value node which currently violates either
+ * of its validity conditions.
+ *
+ * Any client can safely assume:
+ *
+ * - {@link nodeId} will be a stable reference to a node with the same
+ *   {@link BaseNode.nodeId | `nodeId`}.
+ *
+ * - {@link node} will have reference equality to the same node object, within
+ *   the active form instance's {@link RootNode} tree
+ *
+ * - {@link reference} will be a **current** reference to the same node object's
+ *   **computed** {@link BaseNodeState.reference | `currentState.reference`}
+ *
+ * Any client utilizing the engine's reactive APIs (having provided an
+ * {@link OpaqueReactiveObjectFactory}) can safely assume that {@link reference}
+ * will be recomputed and updated in tandem with the affected node's own
+ * computed `currentState.reference` as well.
+ *
+ * @todo this type currently exposes multiple ways to reference the affected
+ * node. This is intended to maximize flexibility: it's not yet clear how
+ * clients will be best served by which reference mechanism. It is expected that
+ * each property will be directly computed from the affected node.
+ */
+export interface DescendantNodeViolationReference {
+	readonly nodeId: NodeID;
+
+	get reference(): string;
+	get violation(): AnyViolation;
+}
+
+/**
+ * Provides access from any ancestor/parent node, to identify any validity
+ * violations present on any of its leaf/value node descendants.
+ *
+ * @see {@link DescendantNodeViolationReference} for details on how descendants
+ * may be referenced when such a violation is present.
+ */
+export interface AncestorNodeValidationState {
+	get violations(): readonly DescendantNodeViolationReference[];
+}
+
+// prettier-ignore
+export type NodeValidationState =
+	| AncestorNodeValidationState
+	| LeafNodeValidationState;

package/src/index.ts

@@ -3,26 +3,38 @@ import { initializeForm as engine__initializeForm } from './instance/index.ts';
 
 export const initializeForm: InitializeForm = engine__initializeForm;
 
+export * as constants from './client/constants.ts';
 export type * from './client/EngineConfig.ts';
 export type * from './client/FormLanguage.ts';
 export type * from './client/GroupNode.ts';
-export type * from './client/OpaqueReactiveObjectFactory.ts';
-export type * from './client/RepeatInstanceNode.ts';
-export type * from './client/RepeatRangeNode.ts';
-export type * from './client/RootNode.ts';
-export type * from './client/SelectNode.ts';
-export type * from './client/StringNode.ts';
-export type * from './client/SubtreeNode.ts';
-export type * from './client/TextRange.ts';
 export type {
 	AnyChildNode,
+	AnyControlNode,
 	AnyLeafNode,
 	AnyNode,
 	AnyParentNode,
+	AnyUnsupportedControlNode,
 	GeneralChildNode,
 	GeneralParentNode,
+	RepeatRangeNode,
 } from './client/hierarchy.ts';
 export type * from './client/index.ts';
+export type * from './client/ModelValueNode.ts';
+export type * from './client/NoteNode.ts';
+export type * from './client/OpaqueReactiveObjectFactory.ts';
+export type * from './client/repeat/RepeatInstanceNode.ts';
+export type * from './client/repeat/RepeatRangeControlledNode.ts';
+export type * from './client/repeat/RepeatRangeUncontrolledNode.ts';
+export type * from './client/RootNode.ts';
+export type * from './client/SelectNode.ts';
+export type * from './client/StringNode.ts';
+export type * from './client/SubtreeNode.ts';
+export type * from './client/TextRange.ts';
+export type * from './client/TriggerNode.ts';
+export type * from './client/unsupported/RangeNode.ts';
+export type * from './client/unsupported/RankNode.ts';
+export type * from './client/unsupported/UploadNode.ts';
+export type * from './client/validation.ts';
 
 // TODO: notwithstanding potential conflicts with parallel work on `web-forms`
 // (former `ui-vue`), these are the last remaining references **outside of
@@ -32,4 +44,4 @@ export type * from './client/index.ts';
 export type {
 	AnySelectDefinition,
 	SelectDefinition,
-} from './body/control/select/SelectDefinition.ts';
+} from './parse/body/control/select/SelectDefinition.ts';

package/src/instance/Group.ts

@@ -1,6 +1,7 @@
 import type { Accessor } from 'solid-js';
 import type { GroupDefinition, GroupNode, GroupNodeAppearances } from '../client/GroupNode.ts';
-import type { TextRange } from '../index.ts';
+import type { TextRange } from '../client/TextRange.ts';
+import type { AncestorNodeValidationState } from '../client/validation.ts';
 import type { ChildrenState } from '../lib/reactivity/createChildrenState.ts';
 import { createChildrenState } from '../lib/reactivity/createChildrenState.ts';
 import type { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
@@ -10,6 +11,7 @@ import type { EngineState } from '../lib/reactivity/node-state/createEngineState
 import type { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
 import { createSharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
 import { createNodeLabel } from '../lib/reactivity/text/createNodeLabel.ts';
+import { createAggregatedViolations } from '../lib/reactivity/validation/createAggregatedViolations.ts';
 import type { DescendantNodeSharedStateSpec } from './abstract/DescendantNode.ts';
 import { DescendantNode } from './abstract/DescendantNode.ts';
 import { buildChildren } from './children.ts';
@@ -41,6 +43,7 @@ export class Group
 	readonly nodeType = 'group';
 	readonly appearances: GroupNodeAppearances;
 	readonly currentState: MaterializedChildren<CurrentState<GroupStateSpec>, GeneralChildNode>;
+	readonly validationState: AncestorNodeValidationState;
 
 	constructor(parent: GeneralParentNode, definition: GroupDefinition) {
 		super(parent, definition);
@@ -51,6 +54,10 @@ export class Group
 
 		this.childrenState = childrenState;
 
+		const sharedStateOptions = {
+			clientStateFactory: this.engineConfig.stateFactory,
+		};
+
 		const state = createSharedNodeState(
 			this.scope,
 			{
@@ -65,9 +72,7 @@ export class Group
 				valueOptions: null,
 				value: null,
 			},
-			{
-				clientStateFactory: this.engineConfig.stateFactory,
-			}
+			sharedStateOptions
 		);
 
 		this.state = state;
@@ -79,6 +84,7 @@ export class Group
 		);
 
 		childrenState.setChildren(buildChildren(this));
+		this.validationState = createAggregatedViolations(this, sharedStateOptions);
 	}
 
 	getChildren(): readonly GeneralChildNode[] {