@getodk/xforms-engine 0.2.0 → 0.3.0

package/dist/body/BodyElementDefinition.d.ts

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

package/dist/body/RepeatElementDefinition.d.ts

@@ -1,8 +1,8 @@
 import { XFormDefinition } from '../XFormDefinition.ts';
+import { LabelDefinition } from '../parse/text/LabelDefinition.ts';
 import { BodyElementDefinitionArray, BodyElementParentContext } from './BodyDefinition.ts';
 import { BodyElementDefinition } from './BodyElementDefinition.ts';
 import { StructureElementAppearanceDefinition } from './appearance/structureElementAppearanceParser.ts';
-import { LabelDefinition } from './text/LabelDefinition.ts';
 
 export declare class RepeatElementDefinition extends BodyElementDefinition<'repeat'> {
     static isCompatible(localName: string): boolean;
@@ -12,7 +12,7 @@ export declare class RepeatElementDefinition extends BodyElementDefinition<'repe
     readonly appearances: StructureElementAppearanceDefinition;
     readonly label: LabelDefinition | null;
     readonly countExpression: string | null;
-    readonly isFixedCount: boolean;
+    readonly noAddRemoveExpression: string | null;
     readonly children: BodyElementDefinitionArray;
     constructor(form: XFormDefinition, parent: BodyElementParentContext, element: Element);
     toJSON(): Omit<this, "toJSON" | "form" | "parent" | "isTranslated" | "registerDependentExpression" | "dependencyExpressions">;

package/dist/body/control/ControlDefinition.d.ts

@@ -1,9 +1,9 @@
 import { XFormDefinition } from '../../XFormDefinition.ts';
 import { ParsedTokenList } from '../../lib/TokenListParser.ts';
+import { HintDefinition } from '../../parse/text/HintDefinition.ts';
+import { LabelDefinition } from '../../parse/text/LabelDefinition.ts';
 import { BodyElementParentContext } from '../BodyDefinition.ts';
 import { BodyElementDefinition } from '../BodyElementDefinition.ts';
-import { HintDefinition } from '../text/HintDefinition.ts';
-import { LabelDefinition } from '../text/LabelDefinition.ts';
 
 type ControlType = 'input' | 'range' | 'rank' | 'select' | 'select1' | 'trigger' | 'upload';
 export declare abstract class ControlDefinition<Type extends ControlType> extends BodyElementDefinition<Type> {

package/dist/body/control/select/ItemDefinition.d.ts

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

package/dist/body/control/select/ItemsetDefinition.d.ts

@@ -1,17 +1,18 @@
-import { ItemsetElement } from '../../../lib/dom/query.ts';
 import { XFormDefinition } from '../../../XFormDefinition.ts';
+import { ItemsetElement } from '../../../lib/dom/query.ts';
+import { ItemsetLabelDefinition } from '../../../parse/text/ItemsetLabelDefinition.ts';
 import { BodyElementDefinition } from '../../BodyElementDefinition.ts';
-import { LabelDefinition } from '../../text/LabelDefinition.ts';
 import { ItemsetNodesetExpression } from './ItemsetNodesetExpression.ts';
 import { ItemsetValueExpression } from './ItemsetValueExpression.ts';
 import { AnySelectDefinition } from './SelectDefinition.ts';
 
 export declare class ItemsetDefinition extends BodyElementDefinition<'itemset'> {
+    readonly parent: AnySelectDefinition;
     readonly category = "support";
     readonly type = "itemset";
     readonly reference: string;
-    readonly label: LabelDefinition | null;
+    readonly label: ItemsetLabelDefinition | null;
     readonly nodes: ItemsetNodesetExpression;
     readonly value: ItemsetValueExpression;
-    constructor(form: XFormDefinition, select: AnySelectDefinition, element: ItemsetElement);
+    constructor(form: XFormDefinition, parent: AnySelectDefinition, element: ItemsetElement);
 }

package/dist/body/group/BaseGroupDefinition.d.ts

@@ -1,8 +1,8 @@
 import { XFormDefinition } from '../../XFormDefinition.ts';
+import { LabelDefinition } from '../../parse/text/LabelDefinition.ts';
 import { BodyElementDefinitionArray, BodyElementParentContext } from '../BodyDefinition.ts';
 import { BodyElementDefinition } from '../BodyElementDefinition.ts';
 import { StructureElementAppearanceDefinition } from '../appearance/structureElementAppearanceParser.ts';
-import { LabelDefinition } from '../text/LabelDefinition.ts';
 
 /**
  * These type names are derived from **and expand upon** the language used in

package/dist/body/group/PresentationGroupDefinition.d.ts

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

package/dist/client/BaseNode.d.ts

@@ -2,6 +2,7 @@ import { AnyNodeDefinition } from '../model/NodeDefinition.ts';
 import { NodeAppearances } from './NodeAppearances.ts';
 import { TextRange } from './TextRange.ts';
 import { InstanceNodeType } from './node-types.ts';
+import { NodeValidationState } from './validation.ts';
 
 export interface BaseNodeState {
     /**
@@ -38,6 +39,17 @@ export interface BaseNodeState {
      * {@link BaseNode.parent | parent node}.
      */
     get relevant(): boolean;
+    /**
+     * 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;
     /**
      * Interfaces for nodes which cannot provide a label should override this to
@@ -91,6 +103,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;
 }
@@ -136,9 +156,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;
 }
 export {};

package/dist/client/GroupNode.d.ts

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

package/dist/client/ModelValueNode.d.ts

@@ -0,0 +1,37 @@
+import { LeafNodeDefinition } from '../model/LeafNodeDefinition.ts';
+import { BaseNode, BaseNodeState } from './BaseNode.ts';
+import { GeneralParentNode } from './hierarchy.ts';
+import { RootNode } from './RootNode.ts';
+import { 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/dist/client/NoteNode.d.ts

@@ -0,0 +1,53 @@
+import { InputDefinition } from '../body/control/InputDefinition.ts';
+import { LeafNodeDefinition } from '../model/LeafNodeDefinition.ts';
+import { BaseNode, BaseNodeState } from './BaseNode.ts';
+import { GeneralParentNode } from './hierarchy.ts';
+import { NodeAppearances } from './NodeAppearances.ts';
+import { RootNode } from './RootNode.ts';
+import { TextRange } from './TextRange.ts';
+import { 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.
+     */
+    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.
+     */
+    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/dist/client/RootNode.d.ts

@@ -3,6 +3,7 @@ import { RootDefinition } from '../model/RootDefinition.ts';
 import { BaseNode, BaseNodeState } from './BaseNode.ts';
 import { ActiveLanguage, FormLanguage, FormLanguages } from './FormLanguage.ts';
 import { GeneralChildNode } from './hierarchy.ts';
+import { AncestorNodeValidationState } from './validation.ts';
 
 export interface RootNodeState extends BaseNodeState {
     /**
@@ -42,6 +43,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
      * significant break in consistency across node types.

package/dist/client/SelectNode.d.ts

@@ -1,14 +1,15 @@
 import { AnySelectDefinition } from '../body/control/select/SelectDefinition.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 { TextRange } from './TextRange.ts';
 import { GeneralParentNode } from './hierarchy.ts';
+import { 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 {
     get children(): null;
@@ -30,7 +31,7 @@ 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>;
@@ -41,6 +42,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/dist/client/StringNode.d.ts

@@ -1,9 +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;
@@ -16,8 +17,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>;
 /**
@@ -34,6 +35,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/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;
@@ -51,4 +52,5 @@ export interface SubtreeNode extends BaseNode {
     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';