@getodk/xforms-engine 0.1.1 → 0.3.0

package/dist/client/StringNode.d.ts

@@ -1,8 +1,10 @@
 import { InputDefinition } from '../body/control/InputDefinition.ts';
-import { ValueNodeDefinition } from '../model/ValueNodeDefinition.ts';
+import { LeafNodeDefinition } from '../model/LeafNodeDefinition.ts';
 import { BaseNode, BaseNodeState } from './BaseNode.ts';
+import { NodeAppearances } from './NodeAppearances.ts';
 import { RootNode } from './RootNode.ts';
 import { GeneralParentNode } from './hierarchy.ts';
+import { LeafNodeValidationState } from './validation.ts';
 
 export interface StringNodeState extends BaseNodeState {
     get children(): null;
@@ -15,9 +17,10 @@ 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
@@ -27,10 +30,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/dist/client/SubtreeNode.d.ts

@@ -2,6 +2,7 @@ import { SubtreeDefinition as BaseSubtreeDefinition } from '../model/SubtreeDefi
 import { BaseNode, BaseNodeState } from './BaseNode.ts';
 import { RootNode } from './RootNode.ts';
 import { GeneralChildNode, GeneralParentNode } from './hierarchy.ts';
+import { AncestorNodeValidationState } from './validation.ts';
 
 export interface SubtreeNodeState extends BaseNodeState {
     get label(): null;
@@ -46,8 +47,10 @@ export interface SubtreeDefinition extends BaseSubtreeDefinition {
  */
 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;
 }

package/dist/client/TextRange.d.ts

@@ -1,6 +1,63 @@
 import { ActiveLanguage } from './FormLanguage.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()]`
+ *
+ * - 'static':
+ *   - `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).
+ */
+export type TextChunkSource = 'output' | 'reference' | 'translation' | 'static';
 /**
  * @todo This (and everything else to do with {@link TextRange}s is for
  * illustration purposes, as a starting point where any particular detail is of
@@ -18,6 +75,31 @@ export interface TextChunk {
     get asString(): string;
     get formatted(): unknown;
 }
+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.
+ */
+export type TextOrigin = 'form' | 'form-derived' | 'engine';
 /**
  * Represents aspects of a form which produce text, which _might_ be:
  *
@@ -48,7 +130,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>;
     get asString(): string;

package/dist/client/constants.d.ts

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

package/dist/client/hierarchy.d.ts

@@ -1,13 +1,23 @@
 import { ExpandUnion } from '../../../common/types/helpers.d.ts';
 import { GroupNode } from './GroupNode.ts';
-import { RepeatInstanceNode } from './RepeatInstanceNode.ts';
-import { RepeatRangeNode } from './RepeatRangeNode.ts';
+import { ModelValueNode } from './ModelValueNode.ts';
+import { NoteNode } from './NoteNode.ts';
+import { RepeatInstanceNode } from './repeat/RepeatInstanceNode.ts';
+import { RepeatRangeControlledNode } from './repeat/RepeatRangeControlledNode.ts';
+import { RepeatRangeUncontrolledNode } from './repeat/RepeatRangeUncontrolledNode.ts';
 import { RootNode } from './RootNode.ts';
 import { SelectNode } from './SelectNode.ts';
 import { StringNode } from './StringNode.ts';
 import { SubtreeNode } from './SubtreeNode.ts';
 
-export type AnyLeafNode = SelectNode | StringNode;
+export type AnyControlNode = NoteNode | SelectNode | StringNode;
+export type AnyLeafNode = AnyControlNode | ModelValueNode;
+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 | SubtreeNode | GroupNode | RepeatInstanceNode;
 /**
  * Any of the concrete node types which may be a parent of any other node.
  *
@@ -17,7 +27,7 @@ export type AnyLeafNode = SelectNode | StringNode;
  * - Repeat instances should (continue to) specify {@link RepeatRangeNode}.
  * - All other child nodes should specify {@link GeneralParentNode}.
  */
-export type AnyParentNode = RootNode | SubtreeNode | GroupNode | RepeatRangeNode | RepeatInstanceNode;
+export type AnyParentNode = GeneralParentNode | RepeatRangeNode;
 /**
  * Any of the concrete node types a client may get from the engine's form
  * representation. This union should be updated when any new concrete node type
@@ -27,11 +37,6 @@ export type AnyParentNode = RootNode | SubtreeNode | GroupNode | RepeatRangeNode
  * @see {@link GeneralChildNode}, which is derived from this type
  */
 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/dist/client/node-types.d.ts

@@ -1 +1,2 @@
-export type InstanceNodeType = 'root' | 'repeat-range' | 'repeat-instance' | 'group' | 'subtree' | 'select' | 'string';
+export type RepeatRangeNodeType = 'repeat-range:controlled' | 'repeat-range:uncontrolled';
+export type InstanceNodeType = 'root' | RepeatRangeNodeType | 'repeat-instance' | 'group' | 'subtree' | 'model-value' | 'note' | 'select' | 'string';

package/dist/client/{RepeatRangeNode.d.ts → repeat/BaseRepeatRangeNode.d.ts}

@@ -1,11 +1,14 @@
-import { RepeatSequenceDefinition } from '../model/RepeatSequenceDefinition.ts';
-import { BaseNode, BaseNodeState } from './BaseNode.ts';
+import { AnyRepeatRangeDefinition } from '../../model/RepeatRangeDefinition.ts';
+import { BaseNode, BaseNodeState } from '../BaseNode.ts';
+import { NodeAppearances } from '../NodeAppearances.ts';
+import { RootNode } from '../RootNode.ts';
+import { TextRange } from '../TextRange.ts';
+import { GeneralParentNode } from '../hierarchy.ts';
+import { RepeatRangeNodeType } from '../node-types.ts';
+import { AncestorNodeValidationState } from '../validation.ts';
 import { RepeatInstanceNode } from './RepeatInstanceNode.ts';
-import { RootNode } from './RootNode.ts';
-import { TextRange } from './TextRange.ts';
-import { GeneralParentNode } from './hierarchy.ts';
 
-export interface RepeatRangeNodeState extends BaseNodeState {
+export interface BaseRepeatRangeNodeState extends BaseNodeState {
     get hint(): null;
     get label(): TextRange<'label'> | null;
     /**
@@ -14,16 +17,17 @@ 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[];
     get valueOptions(): null;
     get value(): null;
 }
+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
@@ -82,14 +86,14 @@ export interface RepeatRangeNodeState extends BaseNodeState {
  * 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';
-    readonly definition: RepeatSequenceDefinition;
+export interface BaseRepeatRangeNode extends BaseNode {
+    readonly nodeType: RepeatRangeNodeType;
+    readonly appearances: RepeatRangeNodeAppearances;
+    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/dist/client/{RepeatInstanceNode.d.ts → repeat/RepeatInstanceNode.d.ts}

@@ -1,9 +1,10 @@
-import { RepeatInstanceDefinition } from '../model/RepeatInstanceDefinition.ts';
-import { RepeatTemplateDefinition } from '../model/RepeatTemplateDefinition.ts';
-import { BaseNode, BaseNodeState } from './BaseNode.ts';
-import { RepeatRangeNode } from './RepeatRangeNode.ts';
-import { RootNode } from './RootNode.ts';
-import { GeneralChildNode } from './hierarchy.ts';
+import { RepeatInstanceDefinition } from '../../model/RepeatInstanceDefinition.ts';
+import { RepeatTemplateDefinition } from '../../model/RepeatTemplateDefinition.ts';
+import { BaseNode, BaseNodeState } from '../BaseNode.ts';
+import { GeneralChildNode, RepeatRangeNode } from '../hierarchy.ts';
+import { NodeAppearances } from '../NodeAppearances.ts';
+import { RootNode } from '../RootNode.ts';
+import { AncestorNodeValidationState } from '../validation.ts';
 
 export interface RepeatInstanceNodeState extends BaseNodeState {
     get hint(): null;
@@ -12,8 +13,10 @@ export interface RepeatInstanceNodeState extends BaseNodeState {
     get value(): null;
 }
 export type RepeatDefinition = RepeatInstanceDefinition | RepeatTemplateDefinition;
+export type RepeatInstanceNodeAppearances = NodeAppearances<RepeatDefinition>;
 export interface RepeatInstanceNode extends BaseNode {
     readonly nodeType: 'repeat-instance';
+    readonly appearances: RepeatInstanceNodeAppearances;
     readonly definition: RepeatDefinition;
     readonly root: RootNode;
     /**
@@ -22,8 +25,9 @@ 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/dist/client/repeat/RepeatRangeControlledNode.d.ts

@@ -0,0 +1,19 @@
+import { ControlledRepeatRangeDefinition } from '../../model/RepeatRangeDefinition.ts';
+import { BaseRepeatRangeNode, BaseRepeatRangeNodeState } from './BaseRepeatRangeNode.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/dist/client/repeat/RepeatRangeUncontrolledNode.d.ts

@@ -0,0 +1,20 @@
+import { UncontrolledRepeatRangeDefinition } from '../../model/RepeatRangeDefinition.ts';
+import { RootNode } from '../RootNode.ts';
+import { 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/dist/client/validation.d.ts

@@ -0,0 +1,163 @@
+import { NodeID } from '../instance/identity.ts';
+import { TextRange } from './TextRange.ts';
+
+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.
+ */
+export type ViolationMessageSource = 'form' | 'engine';
+/**
+ * @see {@link ViolationMessage.asString}
+ */
+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[];
+}
+export type NodeValidationState = AncestorNodeValidationState | LeafNodeValidationState;
+export {};

package/dist/expression/DependentExpression.d.ts

@@ -1,9 +1,11 @@
 import { XFormsXPathEvaluator } from '@getodk/xpath';
+import { ConstantExpression, ConstantTruthyExpression } from '../parse/xpath/semantic-analysis.ts';
 import { DependencyContext } from './DependencyContext.ts';
 
 declare const evaluatorMethodsByResultType: {
     readonly boolean: "evaluateBoolean";
     readonly nodes: "evaluateNodes";
+    readonly number: "evaluateNumber";
     readonly string: "evaluateString";
 };
 type EvaluatorMethodsByResultType = typeof evaluatorMethodsByResultType;
@@ -11,10 +13,6 @@ export type DependentExpressionResultType = keyof EvaluatorMethodsByResultType;
 export type DependentExpressionEvaluatorMethod<Type extends DependentExpressionResultType> = EvaluatorMethodsByResultType[Type];
 export type DependentExpressionResult<Type extends DependentExpressionResultType> = ReturnType<XFormsXPathEvaluator[DependentExpressionEvaluatorMethod<Type>]>;
 interface SemanticDependencyOptions {
-    /**
-     * @default false
-     */
-    readonly parentContext?: boolean | undefined;
     /**
      * @default false
      */
@@ -25,19 +23,25 @@ interface DependentExpressionOptions {
      * @default false
      */
     readonly ignoreContextReference?: boolean;
-    /**
-     * @default true
-     */
-    readonly ignoreNullExpressions?: boolean;
     readonly semanticDependencies?: SemanticDependencyOptions;
 }
+export interface ConstantDependentExpression<Type extends DependentExpressionResultType> extends DependentExpression<Type> {
+    readonly expression: ConstantExpression;
+}
+export interface ConstantTruthyDependentExpression extends ConstantDependentExpression<'boolean'> {
+    readonly expression: ConstantTruthyExpression;
+}
 export declare class DependentExpression<Type extends DependentExpressionResultType> {
     readonly resultType: Type;
     readonly expression: string;
     readonly dependencyReferences: ReadonlySet<string>;
     readonly isTranslated: boolean;
     readonly evaluatorMethod: DependentExpressionEvaluatorMethod<Type>;
+    readonly constantExpression: ConstantExpression | null;
+    readonly constantTruthyExpression: ConstantTruthyExpression | null;
     constructor(context: DependencyContext, resultType: Type, expression: string, options?: DependentExpressionOptions);
+    isConstantExpression(): this is ConstantDependentExpression<Type>;
+    isConstantTruthyExpression(): this is ConstantTruthyDependentExpression;
     toString(): string | null;
 }
 export type AnyDependentExpression = DependentExpression<any>;

package/dist/index.d.ts

@@ -1,17 +1,22 @@
 import { InitializeForm } from './index.ts';
 
 export declare const initializeForm: 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 { AnyChildNode, AnyControlNode, AnyLeafNode, AnyNode, AnyParentNode, 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/RepeatInstanceNode.ts';
-export type * from './client/RepeatRangeNode.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 { AnyChildNode, AnyLeafNode, AnyNode, AnyParentNode, GeneralChildNode, GeneralParentNode, } from './client/hierarchy.ts';
-export type * from './client/index.ts';
+export type * from './client/validation.ts';
 export type { AnySelectDefinition, SelectDefinition, } from './body/control/select/SelectDefinition.ts';