@getodk/xforms-engine 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getodk/xforms-engine",
-  "version": "0.2.0",
+  "version": "0.4.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.17.0 || ^22.8.0",
+    "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.22"
   },
   "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.25.2",
+    "@getodk/tree-sitter-xpath": "0.1.2",
+    "@getodk/xpath": "0.2.0",
+    "@playwright/test": "^1.46.1",
+    "@vitest/browser": "^2.0.5",
     "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",
-    "vite-plugin-dts": "^3.9.1",
+    "jsdom": "^25.0.0",
+    "typedoc": "^0.26.6",
+    "vite": "^5.4.3",
+    "vite-plugin-dts": "^4.1.0",
     "vite-plugin-no-bundle": "^4.0.0",
-    "vitest": "^1.6.0"
+    "vitest": "^2.0.5"
   },
   "peerDependencies": {
-    "solid-js": "^1.8.17"
+    "solid-js": "^1.8.18"
   },
   "peerDependenciesMeta": {
     "solid-js": {

package/src/client/BaseNode.ts

@@ -1,9 +1,14 @@
 import type { TokenListParser } from '../lib/TokenListParser.ts';
-import type { AnyNodeDefinition } from '../model/NodeDefinition.ts';
+import type { AnyNodeDefinition } from '../parse/model/NodeDefinition.ts';
 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

@@ -1,9 +1,10 @@
-import type { AnyGroupElementDefinition } from '../body/BodyDefinition.ts';
-import type { SubtreeDefinition } from '../model/SubtreeDefinition.ts';
+import type { AnyGroupElementDefinition } from '../parse/body/BodyDefinition.ts';
+import type { SubtreeDefinition } from '../parse/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;
@@ -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 '../parse/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

@@ -1,5 +1,5 @@
 import type { ParsedTokenList } from '../lib/TokenListParser.ts';
-import type { NodeDefinition } from '../model/NodeDefinition.ts';
+import type { NodeDefinition } from '../parse/model/NodeDefinition.ts';
 
 /**
  * - Provides a means to distinguish between internal and client-facing names

package/src/client/NoteNode.ts

@@ -0,0 +1,74 @@
+import type { InputDefinition } from '../parse/body/control/InputDefinition.ts';
+import type { LeafNodeDefinition } from '../parse/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,8 +1,9 @@
-import type { BodyClassList } from '../body/BodyDefinition.ts';
-import type { RootDefinition } from '../model/RootDefinition.ts';
+import type { BodyClassList } from '../parse/body/BodyDefinition.ts';
+import type { RootDefinition } from '../parse/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 { AnySelectDefinition } from '../parse/body/control/select/SelectDefinition.ts';
+import type { LeafNodeDefinition } from '../parse/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 { InputDefinition } from '../parse/body/control/InputDefinition.ts';
+import type { LeafNodeDefinition } from '../parse/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

@@ -1,7 +1,8 @@
-import type { SubtreeDefinition as BaseSubtreeDefinition } from '../model/SubtreeDefinition.ts';
+import type { SubtreeDefinition as BaseSubtreeDefinition } from '../parse/model/SubtreeDefinition.ts';
 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;
 }

package/src/client/TextRange.ts

@@ -1,7 +1,69 @@
 import type { ActiveLanguage } from './FormLanguage.ts';
 import type { RootNodeState } from './RootNode.ts';
 
-export type TextChunkSource = 'itext' | 'output' | 'static';
+/**
+ * **COMMENTARY**
+ *
+ * The spec makes naming and mapping these cases a bit more complex than would
+ * be ideal. The intent is to clearly identify distinct text definitions (and
+ * sub-structural parts) from a source form, in a way that semantically lines up
+ * with the ways they will need to be handled at runtime and conveyed to
+ * clients. This is the mapping:
+ *
+ * - 'output': All output values, i.e.:
+ *   - `output/@value`
+ *
+ * - 'translation':
+ *
+ *   - Valid XPath translation expressions, in a context accepting mixed
+ *     translation/static syntax, i.e.:
+ *
+ *     - `h:head//bind/@jr:constraintMsg[is-translation-expr()]`
+ *     - `h:head//bind/@jr:requiredMsg[is-translation-expr()]`
+ *
+ *       Here, `is-translation-expr()` is a fictional shorthand for checking
+ *       that the attribute's value is a valid `jr:itext(...)` FunctionCall
+ *       expression. Note that, per spec, these attributes **do not accept
+ *       arbitrary XPath expressions**! The non-translation case is treated as
+ *       static text, not parsed for e.g. an XPath [string] Literal expression.
+ *       This is why we have introduced this 'translation' case, distinct from
+ *       'reference', which previously handled translated labels and hints.
+ *
+ *   - Valid XPath translation expressions, in a context accepting arbitrary
+ *     XPath expressions, i.e.:
+ *
+ *     - `h:body//label/@ref[is-translation-expr()]`
+ *
+ * - 'literal':
+ *   - `h:head//bind/@jr:constraintMsg[not(is-translation-expr())]`
+ *   - `h:head//bind/@jr:requiredMsg[not(is-translation-expr())]`
+ *   - `h:body//label/text()`
+ *   - `h:body//hint/text()`
+ *
+ *   (See notes above for clarification of `is-translation-expr()`.)
+ *
+ * - 'reference': Any XPath **non-translation** expression defined as a label's
+ *   (or hint's) `ref` attribute, i.e.
+ *   - `h:body//label/@ref[not(is-translation-expr())]`
+ *   - `h:body//hint/@ref[not(is-translation-expr())]`
+ *
+ *   (See notes above for clarification of `is-translation-expr()`.)
+ *
+ * @todo It's unclear whether this will all become simpler or more compelex when
+ * we add support for outputs in translations. In theory, the actual translation
+ * `<text>` nodes map quite well to the `TextRange` concept (i.e. they are a
+ * range of static and output chunks, just like labels and hints). The potential
+ * for complications arise from XPath implementation details being largely
+ * opaque (as in, the `jr:itext` implementation is encapsulated in the `xpath`
+ * package, and the engine doesn't really deal with itext translations at the
+ * node level at all).
+ */
+// prettier-ignore
+export type TextChunkSource =
+	| 'literal'
+	| 'output'
+	| 'reference'
+	| 'translation';
 
 /**
  * @todo This (and everything else to do with {@link TextRange}s is for
@@ -23,6 +85,39 @@ export interface TextChunk {
 	get formatted(): unknown;
 }
 
+// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+export type ElementTextRole = 'hint' | 'label' | 'item-label';
+export type ValidationTextRole = 'constraintMsg' | 'requiredMsg';
+export type TextRole = ElementTextRole | ValidationTextRole;
+
+/**
+ * Specifies the origin of a {@link TextRange}.
+ *
+ * - 'form': text is computed from the form definition, as specified for the
+ *   {@link TextRole}. User-facing clients should present text with this origin
+ *   where appropriate.
+ *
+ * - 'form-derived': the form definition lacks a text definition for the
+ *   {@link TextRole}, but an appropriate one has been derived from a related
+ *   (and semantically appropriate) aspect of the form (example: a select item
+ *   without a label may derive that label from the item's value). User-facing
+ *   clients should generally present text with this origin where provided; this
+ *   origin clarifies the source of such text.
+ *
+ * - 'engine': the form definition lacks a definition for the {@link TextRole},
+ *   but provides a constant default in its absence. User facing clients may
+ *   disregard these constant text values, or may use them where a sensible
+ *   default is desired. Clients may also use these constants as keys for
+ *   translation purposes, as appropriate. Non-user facing clients may reference
+ *   these constants for e.g. testing purposes.
+ */
+// prettier-ignore
+export type TextOrigin =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| 'form'
+	| 'form-derived'
+	| 'engine';
+
 /**
  * Represents aspects of a form which produce text, which _might_ be:
  *
@@ -53,7 +148,8 @@ export interface TextChunk {
  * a text range's role may correspond to the "short" or "guidance" `form` of a
  * {@link https://getodk.github.io/xforms-spec/#languages | translation}).
  */
-export interface TextRange<Role extends string | null = null> {
+export interface TextRange<Role extends TextRole, Origin extends TextOrigin = TextOrigin> {
+	readonly origin: Origin;
 	readonly role: Role;
 
 	[Symbol.iterator](): Iterable<TextChunk>;

package/src/client/TriggerNode.ts

@@ -0,0 +1,29 @@
+import type { UnknownAppearanceDefinition } from '../parse/body/appearance/unknownAppearanceParser.ts';
+import type { TriggerControlDefinition } from '../parse/body/control/TriggerControlDefinition.ts';
+import type { LeafNodeDefinition } from '../parse/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 TriggerNodeState extends BaseNodeState {
+	get children(): null;
+	get valueOptions(): null;
+	get value(): boolean;
+}
+
+export interface TriggerNodeDefinition extends LeafNodeDefinition {
+	readonly bodyElement: TriggerControlDefinition;
+}
+
+export interface TriggerNode extends BaseNode {
+	readonly nodeType: 'trigger';
+	readonly definition: TriggerNodeDefinition;
+	readonly appearances: UnknownAppearanceDefinition;
+	readonly root: RootNode;
+	readonly parent: GeneralParentNode;
+	readonly currentState: TriggerNodeState;
+	readonly validationState: LeafNodeValidationState;
+
+	setValue(value: boolean): RootNode;
+}

package/src/client/constants.ts

@@ -0,0 +1,10 @@
+import type { ValidationTextRole } from './TextRange.ts';
+
+export const VALIDATION_TEXT = {
+	constraintMsg: 'Condition not satisfied: constraint',
+	requiredMsg: 'Condition not satisfied: required',
+} as const satisfies Record<ValidationTextRole, string>;
+
+type ValidationTextDefaults = typeof VALIDATION_TEXT;
+
+export type ValidationTextDefault<Role extends ValidationTextRole> = ValidationTextDefaults[Role];