@getodk/xforms-engine 0.2.0 → 0.4.0

package/dist/client/BaseNode.d.ts

@@ -1,8 +1,8 @@
-import { AnyNodeDefinition } from '../model/NodeDefinition.ts';
+import { AnyNodeDefinition } from '../parse/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 {
     /**
      * Location path reference to the node's primary instance state. This property
@@ -38,6 +38,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 +102,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 +155,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/EngineConfig.d.ts

@@ -1,5 +1,4 @@
 import { OpaqueReactiveObjectFactory } from './OpaqueReactiveObjectFactory.ts';
-
 /**
  * @todo this is currently a strict subset of the web standard `Response`. Is it
  * sufficient? Ways it might not be:

package/dist/client/GroupNode.d.ts

@@ -1,10 +1,10 @@
-import { AnyGroupElementDefinition } from '../body/BodyDefinition.ts';
-import { SubtreeDefinition } from '../model/SubtreeDefinition.ts';
+import { AnyGroupElementDefinition } from '../parse/body/BodyDefinition.ts';
+import { SubtreeDefinition } from '../parse/model/SubtreeDefinition.ts';
 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;
     get children(): readonly GeneralChildNode[];
@@ -25,4 +25,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,36 @@
+import { LeafNodeDefinition } from '../parse/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/NodeAppearances.d.ts

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

package/dist/client/NoteNode.d.ts

@@ -0,0 +1,52 @@
+import { InputDefinition } from '../parse/body/control/InputDefinition.ts';
+import { LeafNodeDefinition } from '../parse/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

@@ -1,9 +1,9 @@
-import { BodyClassList } from '../body/BodyDefinition.ts';
-import { RootDefinition } from '../model/RootDefinition.ts';
+import { BodyClassList } from '../parse/body/BodyDefinition.ts';
+import { RootDefinition } from '../parse/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 {
     /**
      * This, along with {@link RootNode.languages} is the most significant break
@@ -42,6 +42,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,14 @@
-import { AnySelectDefinition } from '../body/control/select/SelectDefinition.ts';
-import { ValueNodeDefinition } from '../model/ValueNodeDefinition.ts';
+import { AnySelectDefinition } from '../parse/body/control/select/SelectDefinition.ts';
+import { LeafNodeDefinition } from '../parse/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 +30,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 +41,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,10 +1,10 @@
-import { InputDefinition } from '../body/control/InputDefinition.ts';
-import { ValueNodeDefinition } from '../model/ValueNodeDefinition.ts';
+import { InputDefinition } from '../parse/body/control/InputDefinition.ts';
+import { LeafNodeDefinition } from '../parse/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;
     get valueOptions(): null;
@@ -16,8 +16,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 +34,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

@@ -1,8 +1,8 @@
-import { SubtreeDefinition as BaseSubtreeDefinition } from '../model/SubtreeDefinition.ts';
+import { SubtreeDefinition as BaseSubtreeDefinition } from '../parse/model/SubtreeDefinition.ts';
 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;
     get hint(): null;
@@ -51,4 +51,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,62 @@
 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()]`
+ *
+ * - '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).
+ */
+export type TextChunkSource = 'literal' | 'output' | 'reference' | 'translation';
 /**
  * @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 +74,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 +129,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/TriggerNode.d.ts

@@ -0,0 +1,25 @@
+import { UnknownAppearanceDefinition } from '../parse/body/appearance/unknownAppearanceParser.ts';
+import { TriggerControlDefinition } from '../parse/body/control/TriggerControlDefinition.ts';
+import { LeafNodeDefinition } from '../parse/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 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/dist/client/constants.d.ts

@@ -0,0 +1,8 @@
+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,27 @@
 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;
+import { TriggerNode } from './TriggerNode.ts';
+import { RangeNode } from './unsupported/RangeNode.ts';
+import { RankNode } from './unsupported/RankNode.ts';
+import { UploadNode } from './unsupported/UploadNode.ts';
+export type AnyUnsupportedControlNode = RangeNode | RankNode | UploadNode;
+export type AnyControlNode = NoteNode | SelectNode | StringNode | TriggerNode;
+export type AnyLeafNode = AnyControlNode | AnyUnsupportedControlNode | 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 +31,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 +41,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/index.d.ts

@@ -1,6 +1,5 @@
 import { EngineConfig } from './EngineConfig.ts';
 import { RootNode } from './RootNode.ts';
-
 export type FormResource = Blob | URL | string;
 export interface InitializeFormOptions {
     readonly config: EngineConfig;

package/dist/client/node-types.d.ts

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

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

@@ -1,12 +1,13 @@
-import { RepeatRangeDefinition } from '../model/RepeatRangeDefinition.ts';
-import { BaseNode, BaseNodeState } from './BaseNode.ts';
-import { NodeAppearances } from './NodeAppearances.ts';
+import { AnyRepeatRangeDefinition } from '../../parse/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;
     /**
@@ -15,17 +16,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<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
@@ -84,15 +85,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/dist/client/{RepeatInstanceNode.d.ts → repeat/RepeatInstanceNode.d.ts}

@@ -1,11 +1,10 @@
-import { RepeatInstanceDefinition } from '../model/RepeatInstanceDefinition.ts';
-import { RepeatTemplateDefinition } from '../model/RepeatTemplateDefinition.ts';
-import { BaseNode, BaseNodeState } from './BaseNode.ts';
-import { NodeAppearances } from './NodeAppearances.ts';
-import { RepeatRangeNode } from './RepeatRangeNode.ts';
-import { RootNode } from './RootNode.ts';
-import { GeneralChildNode } from './hierarchy.ts';
-
+import { RepeatInstanceDefinition } from '../../parse/model/RepeatInstanceDefinition.ts';
+import { RepeatTemplateDefinition } from '../../parse/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;
     get children(): readonly GeneralChildNode[];
@@ -25,8 +24,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;
 }