@getodk/xforms-engine 0.1.1 → 0.3.0

package/dist/instance/Group.d.ts

@@ -1,6 +1,7 @@
 import { Accessor } from 'solid-js';
-import { GroupDefinition, GroupNode } from '../client/GroupNode.ts';
-import { TextRange } from '../index.ts';
+import { GroupDefinition, GroupNode, GroupNodeAppearances } from '../client/GroupNode.ts';
+import { TextRange } from '../client/TextRange.ts';
+import { AncestorNodeValidationState } from '../client/validation.ts';
 import { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
 import { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
 import { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
@@ -22,10 +23,11 @@ export declare class Group extends DescendantNode<GroupDefinition, GroupStateSpe
     private readonly childrenState;
     protected readonly state: SharedNodeState<GroupStateSpec>;
     protected engineState: EngineState<GroupStateSpec>;
-    readonly currentState: MaterializedChildren<CurrentState<GroupStateSpec>, GeneralChildNode>;
     readonly nodeType = "group";
+    readonly appearances: GroupNodeAppearances;
+    readonly currentState: MaterializedChildren<CurrentState<GroupStateSpec>, GeneralChildNode>;
+    readonly validationState: AncestorNodeValidationState;
     constructor(parent: GeneralParentNode, definition: GroupDefinition);
-    protected computeReference(parent: GeneralParentNode): string;
     getChildren(): readonly GeneralChildNode[];
 }
 export {};

package/dist/instance/ModelValue.d.ts

@@ -0,0 +1,40 @@
+import { ModelValueNode } from '../client/ModelValueNode.ts';
+import { AnyViolation, LeafNodeValidationState } from '../client/validation.ts';
+import { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
+import { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
+import { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
+import { SimpleAtomicState } from '../lib/reactivity/types.ts';
+import { LeafNodeDefinition } from '../model/LeafNodeDefinition.ts';
+import { DescendantNodeStateSpec, DescendantNode } from './abstract/DescendantNode.ts';
+import { GeneralParentNode } from './hierarchy.ts';
+import { EvaluationContext } from './internal-api/EvaluationContext.ts';
+import { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
+import { ValidationContext } from './internal-api/ValidationContext.ts';
+import { ValueContext } from './internal-api/ValueContext.ts';
+
+export interface ModelValueDefinition extends LeafNodeDefinition {
+    readonly bodyElement: null;
+}
+interface ModelValueStateSpec extends DescendantNodeStateSpec<string> {
+    readonly label: null;
+    readonly hint: null;
+    readonly children: null;
+    readonly value: SimpleAtomicState<string>;
+    readonly valueOptions: null;
+}
+export declare class ModelValue extends DescendantNode<ModelValueDefinition, ModelValueStateSpec, null> implements ModelValueNode, EvaluationContext, SubscribableDependency, ValidationContext, ValueContext<string> {
+    private readonly validation;
+    protected readonly state: SharedNodeState<ModelValueStateSpec>;
+    protected engineState: EngineState<ModelValueStateSpec>;
+    readonly nodeType = "model-value";
+    readonly appearances: null;
+    readonly currentState: CurrentState<ModelValueStateSpec>;
+    get validationState(): LeafNodeValidationState;
+    readonly encodeValue: (value: string) => string;
+    readonly decodeValue: (value: string) => string;
+    constructor(parent: GeneralParentNode, definition: ModelValueDefinition);
+    getViolation(): AnyViolation | null;
+    isBlank(): boolean;
+    getChildren(): readonly [];
+}
+export {};

package/dist/instance/Note.d.ts

@@ -0,0 +1,42 @@
+import { Accessor } from 'solid-js';
+import { NoteNode, NoteNodeAppearances } from '../client/NoteNode.ts';
+import { TextRange } from '../client/TextRange.ts';
+import { AnyViolation, LeafNodeValidationState } from '../client/validation.ts';
+import { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
+import { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
+import { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
+import { ComputedNoteText } from '../lib/reactivity/text/createNoteText.ts';
+import { SimpleAtomicState } from '../lib/reactivity/types.ts';
+import { NoteNodeDefinition } from '../parse/NoteNodeDefinition.ts';
+import { DescendantNodeStateSpec, DescendantNode } from './abstract/DescendantNode.ts';
+import { GeneralParentNode } from './hierarchy.ts';
+import { EvaluationContext } from './internal-api/EvaluationContext.ts';
+import { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
+import { ValidationContext } from './internal-api/ValidationContext.ts';
+import { ValueContext } from './internal-api/ValueContext.ts';
+
+interface NoteStateSpec extends DescendantNodeStateSpec<string> {
+    readonly readonly: Accessor<true>;
+    readonly noteText: ComputedNoteText;
+    readonly label: Accessor<TextRange<'label', 'form'> | null>;
+    readonly hint: Accessor<TextRange<'hint', 'form'> | null>;
+    readonly children: null;
+    readonly value: SimpleAtomicState<string>;
+    readonly valueOptions: null;
+}
+export declare class Note extends DescendantNode<NoteNodeDefinition, NoteStateSpec, null> implements NoteNode, EvaluationContext, SubscribableDependency, ValidationContext, ValueContext<string> {
+    private readonly validation;
+    protected readonly state: SharedNodeState<NoteStateSpec>;
+    protected engineState: EngineState<NoteStateSpec>;
+    readonly nodeType = "note";
+    readonly appearances: NoteNodeAppearances;
+    readonly currentState: CurrentState<NoteStateSpec>;
+    get validationState(): LeafNodeValidationState;
+    readonly encodeValue: (value: string) => string;
+    readonly decodeValue: (value: string) => string;
+    constructor(parent: GeneralParentNode, definition: NoteNodeDefinition);
+    getViolation(): AnyViolation | null;
+    isBlank(): boolean;
+    getChildren(): readonly [];
+}
+export {};

package/dist/instance/Root.d.ts

@@ -1,8 +1,10 @@
 import { XFormsXPathEvaluator } from '@getodk/xpath';
 import { Accessor, Signal } from 'solid-js';
 import { XFormDOM } from '../XFormDOM.ts';
+import { BodyClassList } from '../body/BodyDefinition.ts';
 import { ActiveLanguage, FormLanguage, FormLanguages } from '../client/FormLanguage.ts';
 import { RootNode } from '../client/RootNode.ts';
+import { AncestorNodeValidationState } from '../client/validation.ts';
 import { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
 import { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
 import { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
@@ -29,41 +31,26 @@ interface RootStateSpec {
     readonly activeLanguage: Signal<ActiveLanguage>;
 }
 export declare class Root extends InstanceNode<RootDefinition, RootStateSpec, GeneralChildNode> implements RootNode, EvaluationContext, EvaluationContextRoot, SubscribableDependency, TranslationContext {
-    static initialize(xformDOM: XFormDOM, definition: RootDefinition, engineConfig: InstanceConfig): Promise<Root>;
     private readonly childrenState;
+    readonly hasReadonlyAncestor: () => boolean;
+    readonly isReadonly: () => boolean;
+    readonly hasNonRelevantAncestor: () => boolean;
+    readonly isRelevant: () => boolean;
     protected readonly state: SharedNodeState<RootStateSpec>;
     protected readonly engineState: EngineState<RootStateSpec>;
     readonly nodeType = "root";
+    readonly appearances: null;
+    readonly classes: BodyClassList;
     readonly currentState: MaterializedChildren<CurrentState<RootStateSpec>, GeneralChildNode>;
+    readonly validationState: AncestorNodeValidationState;
     protected readonly instanceDOM: XFormDOM;
     readonly root: this;
     readonly evaluator: XFormsXPathEvaluator;
-    private readonly rootReference;
-    get contextReference(): string;
     readonly contextNode: Element;
     readonly parent: null;
     readonly languages: FormLanguages;
     get activeLanguage(): ActiveLanguage;
-    protected constructor(xformDOM: XFormDOM, definition: RootDefinition, engineConfig: InstanceConfig);
-    /**
-     * Waits until form state is fully initialized.
-     *
-     * As much as possible, all instance state computations are implemented so
-     * that they complete synchronously.
-     *
-     * There is currently one exception: because instance nodes may form
-     * computation dependencies into their descendants as well as their ancestors,
-     * there is an allowance **during form initialization only** to account for
-     * this chicken/egg scenario. Note that this allowance is intentionally,
-     * strictly limited: if form state initialization is not resolved within a
-     * single microtask tick we throw/reject.
-     *
-     * All subsequent computations are always performed synchronously (and we will
-     * use tests to validate this, by utilizing the synchronously returned `Root`
-     * state from client-facing write interfaces).
-     */
-    formStateInitialized(): Promise<void>;
-    protected computeReference(_parent: null, definition: RootDefinition): string;
+    constructor(xformDOM: XFormDOM, definition: RootDefinition, engineConfig: InstanceConfig);
     getChildren(): readonly GeneralChildNode[];
     setLanguage(language: FormLanguage): Root;
     subscribe(): void;

package/dist/instance/SelectField.d.ts

@@ -1,20 +1,22 @@
 import { Accessor } from 'solid-js';
 import { AnySelectDefinition } from '../body/control/select/SelectDefinition.ts';
-import { SelectItem, SelectNode } from '../client/SelectNode.ts';
-import { TextRange } from '../index.ts';
+import { SelectItem, SelectNode, SelectNodeAppearances } from '../client/SelectNode.ts';
+import { TextRange } from '../client/TextRange.ts';
+import { AnyViolation, LeafNodeValidationState } from '../client/validation.ts';
 import { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
 import { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
 import { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
 import { SimpleAtomicState } from '../lib/reactivity/types.ts';
-import { ValueNodeDefinition } from '../model/ValueNodeDefinition.ts';
+import { LeafNodeDefinition } from '../model/LeafNodeDefinition.ts';
 import { Root } from './Root.ts';
 import { DescendantNodeStateSpec, DescendantNode } from './abstract/DescendantNode.ts';
 import { GeneralParentNode } from './hierarchy.ts';
 import { EvaluationContext } from './internal-api/EvaluationContext.ts';
 import { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
+import { ValidationContext } from './internal-api/ValidationContext.ts';
 import { ValueContext } from './internal-api/ValueContext.ts';
 
-export interface SelectFieldDefinition extends ValueNodeDefinition {
+export interface SelectFieldDefinition extends LeafNodeDefinition {
     readonly bodyElement: AnySelectDefinition;
 }
 interface SelectFieldStateSpec extends DescendantNodeStateSpec<readonly SelectItem[]> {
@@ -24,22 +26,26 @@ interface SelectFieldStateSpec extends DescendantNodeStateSpec<readonly SelectIt
     readonly value: SimpleAtomicState<readonly SelectItem[]>;
     readonly valueOptions: Accessor<readonly SelectItem[]>;
 }
-export declare class SelectField extends DescendantNode<SelectFieldDefinition, SelectFieldStateSpec, null> implements SelectNode, EvaluationContext, SubscribableDependency, ValueContext<readonly SelectItem[]> {
+export declare class SelectField extends DescendantNode<SelectFieldDefinition, SelectFieldStateSpec, null> implements SelectNode, EvaluationContext, SubscribableDependency, ValidationContext, ValueContext<readonly SelectItem[]> {
     private readonly selectExclusive;
+    private readonly validation;
     protected readonly state: SharedNodeState<SelectFieldStateSpec>;
     protected engineState: EngineState<SelectFieldStateSpec>;
     readonly nodeType = "select";
+    readonly appearances: SelectNodeAppearances;
     readonly currentState: CurrentState<SelectFieldStateSpec>;
+    get validationState(): LeafNodeValidationState;
     readonly encodeValue: (runtimeValue: readonly SelectItem[]) => string;
     readonly decodeValue: (instanceValue: string) => readonly SelectItem[];
     protected readonly getValueOptions: Accessor<readonly SelectItem[]>;
     constructor(parent: GeneralParentNode, definition: SelectFieldDefinition);
+    getViolation(): AnyViolation | null;
     protected getSelectItemsByValue(valueOptions?: readonly SelectItem[]): ReadonlyMap<string, SelectItem>;
-    protected computeReference(parent: GeneralParentNode): string;
     protected updateSelectedItemValues(values: readonly string[]): void;
     protected setSelectedItemValue(value: string | null): void;
     select(selectedItem: SelectItem): Root;
     deselect(deselectedItem: SelectItem): Root;
     getChildren(): readonly [];
+    isBlank(): boolean;
 }
 export {};

package/dist/instance/StringField.d.ts

@@ -1,21 +1,23 @@
 import { Accessor } from 'solid-js';
 import { InputDefinition } from '../body/control/InputDefinition.ts';
-import { StringNode } from '../client/StringNode.ts';
-import { TextRange } from '../index.ts';
+import { StringNode, StringNodeAppearances } from '../client/StringNode.ts';
+import { TextRange } from '../client/TextRange.ts';
+import { AnyViolation, LeafNodeValidationState } from '../client/validation.ts';
 import { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
 import { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
 import { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
 import { SimpleAtomicState } from '../lib/reactivity/types.ts';
-import { ValueNodeDefinition } from '../model/ValueNodeDefinition.ts';
+import { LeafNodeDefinition } from '../model/LeafNodeDefinition.ts';
 import { Root } from './Root.ts';
 import { DescendantNodeStateSpec, DescendantNode } from './abstract/DescendantNode.ts';
 import { GeneralParentNode } from './hierarchy.ts';
 import { EvaluationContext } from './internal-api/EvaluationContext.ts';
 import { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
+import { ValidationContext } from './internal-api/ValidationContext.ts';
 import { ValueContext } from './internal-api/ValueContext.ts';
 
-export interface StringFieldDefinition extends ValueNodeDefinition {
-    readonly bodyElement: InputDefinition | null;
+export interface StringFieldDefinition extends LeafNodeDefinition {
+    readonly bodyElement: InputDefinition;
 }
 interface StringFieldStateSpec extends DescendantNodeStateSpec<string> {
     readonly label: Accessor<TextRange<'label'> | null>;
@@ -24,15 +26,19 @@ interface StringFieldStateSpec extends DescendantNodeStateSpec<string> {
     readonly value: SimpleAtomicState<string>;
     readonly valueOptions: null;
 }
-export declare class StringField extends DescendantNode<StringFieldDefinition, StringFieldStateSpec, null> implements StringNode, EvaluationContext, SubscribableDependency, ValueContext<string> {
+export declare class StringField extends DescendantNode<StringFieldDefinition, StringFieldStateSpec, null> implements StringNode, EvaluationContext, SubscribableDependency, ValidationContext, ValueContext<string> {
+    private readonly validation;
     protected readonly state: SharedNodeState<StringFieldStateSpec>;
     protected engineState: EngineState<StringFieldStateSpec>;
     readonly nodeType = "string";
+    readonly appearances: StringNodeAppearances;
     readonly currentState: CurrentState<StringFieldStateSpec>;
+    get validationState(): LeafNodeValidationState;
     readonly encodeValue: (value: string) => string;
     readonly decodeValue: (value: string) => string;
     constructor(parent: GeneralParentNode, definition: StringFieldDefinition);
-    protected computeReference(parent: GeneralParentNode): string;
+    getViolation(): AnyViolation | null;
+    isBlank(): boolean;
     getChildren(): readonly [];
     setValue(value: string): Root;
 }

package/dist/instance/Subtree.d.ts

@@ -1,5 +1,6 @@
 import { Accessor } from 'solid-js';
 import { SubtreeDefinition, SubtreeNode } from '../client/SubtreeNode.ts';
+import { AncestorNodeValidationState } from '../client/validation.ts';
 import { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
 import { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
 import { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
@@ -22,9 +23,10 @@ export declare class Subtree extends DescendantNode<SubtreeDefinition, SubtreeSt
     protected readonly state: SharedNodeState<SubtreeStateSpec>;
     protected engineState: EngineState<SubtreeStateSpec>;
     readonly nodeType = "subtree";
+    readonly appearances: null;
     readonly currentState: MaterializedChildren<CurrentState<SubtreeStateSpec>, GeneralChildNode>;
+    readonly validationState: AncestorNodeValidationState;
     constructor(parent: GeneralParentNode, definition: SubtreeDefinition);
-    protected computeReference(parent: GeneralParentNode): string;
     getChildren(): readonly GeneralChildNode[];
 }
 export {};

package/dist/instance/abstract/DescendantNode.d.ts

@@ -2,14 +2,13 @@ import { XFormsXPathEvaluator } from '@getodk/xpath';
 import { Accessor } from 'solid-js';
 import { BaseNode } from '../../client/BaseNode.ts';
 import { AnyDescendantNodeDefinition } from '../../model/DescendentNodeDefinition.ts';
+import { LeafNodeDefinition } from '../../model/LeafNodeDefinition.ts';
 import { AnyNodeDefinition } from '../../model/NodeDefinition.ts';
 import { RepeatInstanceDefinition } from '../../model/RepeatInstanceDefinition.ts';
-import { ValueNodeDefinition } from '../../model/ValueNodeDefinition.ts';
-import { RepeatRange } from '../RepeatRange.ts';
-import { Root } from '../Root.ts';
-import { AnyChildNode, GeneralParentNode } from '../hierarchy.ts';
+import { AnyChildNode, GeneralParentNode, RepeatRange } from '../hierarchy.ts';
 import { EvaluationContext } from '../internal-api/EvaluationContext.ts';
 import { SubscribableDependency } from '../internal-api/SubscribableDependency.ts';
+import { Root } from '../Root.ts';
 import { InstanceNodeStateSpec, InstanceNode } from './InstanceNode.ts';
 
 export interface DescendantNodeSharedStateSpec {
@@ -20,18 +19,25 @@ export interface DescendantNodeSharedStateSpec {
 }
 export type DescendantNodeStateSpec<Value = never> = InstanceNodeStateSpec<Value> & DescendantNodeSharedStateSpec;
 export type DescendantNodeDefinition = Extract<AnyNodeDefinition, AnyDescendantNodeDefinition>;
-export type DescendantNodeParent<Definition extends DescendantNodeDefinition> = Definition extends ValueNodeDefinition ? GeneralParentNode : Definition extends RepeatInstanceDefinition ? RepeatRange : GeneralParentNode;
+export type DescendantNodeParent<Definition extends DescendantNodeDefinition> = Definition extends LeafNodeDefinition ? GeneralParentNode : Definition extends RepeatInstanceDefinition ? RepeatRange : GeneralParentNode;
 export type AnyDescendantNode = DescendantNode<DescendantNodeDefinition, DescendantNodeStateSpec<any>, any>;
+interface DescendantNodeOptions {
+    readonly computeReference?: Accessor<string>;
+}
 export declare abstract class DescendantNode<Definition extends DescendantNodeDefinition, Spec extends DescendantNodeStateSpec<any>, Child extends AnyChildNode | null = null> extends InstanceNode<Definition, Spec, Child> implements BaseNode, EvaluationContext, SubscribableDependency {
     readonly parent: DescendantNodeParent<Definition>;
     readonly definition: Definition;
+    readonly hasReadonlyAncestor: Accessor<boolean>;
+    readonly isSelfReadonly: Accessor<boolean>;
+    readonly isReadonly: Accessor<boolean>;
+    readonly hasNonRelevantAncestor: Accessor<boolean>;
+    readonly isSelfRelevant: Accessor<boolean>;
+    readonly isRelevant: Accessor<boolean>;
+    readonly isRequired: Accessor<boolean>;
     readonly root: Root;
     readonly evaluator: XFormsXPathEvaluator;
     readonly contextNode: Element;
-    constructor(parent: DescendantNodeParent<Definition>, definition: Definition);
-    protected computeChildStepReference(parent: DescendantNodeParent<Definition>): string;
-    protected abstract computeReference(parent: DescendantNodeParent<Definition>, definition: Definition): string;
-    protected buildSharedStateSpec(parent: DescendantNodeParent<Definition>, definition: Definition): DescendantNodeSharedStateSpec;
+    constructor(parent: DescendantNodeParent<Definition>, definition: Definition, options?: DescendantNodeOptions);
     protected createContextNode(parentContextNode: Element, nodeName: string): Element;
     /**
      * Currently expected to be overridden by...
@@ -74,3 +80,4 @@ export declare abstract class DescendantNode<Definition extends DescendantNodeDe
      */
     remove(this: AnyChildNode): void;
 }
+export {};

package/dist/instance/abstract/InstanceNode.d.ts

@@ -1,7 +1,9 @@
 import { XFormsXPathEvaluator } from '@getodk/xpath';
 import { Accessor, Signal } from 'solid-js';
 import { BaseNode } from '../../client/BaseNode.ts';
+import { NodeAppearances } from '../../client/NodeAppearances.ts';
 import { InstanceNodeType } from '../../client/node-types.ts';
+import { NodeValidationState } from '../../client/validation.ts';
 import { TextRange } from '../../index.ts';
 import { CurrentState } from '../../lib/reactivity/node-state/createCurrentState.ts';
 import { EngineState } from '../../lib/reactivity/node-state/createEngineState.ts';
@@ -28,9 +30,6 @@ export interface InstanceNodeStateSpec<Value = never> {
     readonly value: Signal<Value> | SimpleAtomicState<Value> | null;
 }
 type AnyInstanceNode = InstanceNode<AnyNodeDefinition, InstanceNodeStateSpec<any>, any>;
-interface InitializedStateOptions<T, K extends keyof T> {
-    readonly uninitializedFallback: T[K];
-}
 /**
  * This type has the same effect as {@link MaterializedChildren}, but abstractly
  * handles leaf node types as well.
@@ -38,52 +37,53 @@ interface InitializedStateOptions<T, K extends keyof T> {
 export type InstanceNodeCurrentState<Spec extends InstanceNodeStateSpec<any>, Child> = CurrentState<Omit<Spec, 'children'>> & {
     readonly children: [Child] extends [AnyChildNode] ? readonly Child[] : null;
 };
+interface ComputableReferenceNode {
+    readonly parent: AnyParentNode | null;
+    readonly definition: AnyNodeDefinition;
+}
+type ComputeInstanceNodeReference = <This extends ComputableReferenceNode>(this: This, parent: This['parent'], definition: This['definition']) => string;
+export interface InstanceNodeOptions {
+    readonly computeReference?: () => string;
+}
 export declare abstract class InstanceNode<Definition extends AnyNodeDefinition, Spec extends InstanceNodeStateSpec<any>, Child extends AnyChildNode | null = null> implements BaseNode, EvaluationContext, SubscribableDependency {
     readonly engineConfig: InstanceConfig;
     readonly parent: AnyParentNode | null;
     readonly definition: Definition;
-    protected readonly isStateInitialized: Accessor<boolean>;
     protected abstract readonly state: SharedNodeState<Spec>;
     protected abstract readonly engineState: EngineState<Spec>;
     /**
-     * Provides a generalized mechanism for accessing a reactive state value
-     * during a node's construction, while {@link engineState} is still being
-     * defined and thus isn't assigned.
-     *
-     * The fallback value specified in {@link options} will be returned on access
-     * until {@link isStateInitialized} returns true. This ensures:
-     *
-     * - a value of the expected type will be available
-     * - any read access will become reactive to the actual state, once it has
-     *   been initialized and {@link engineState} is assigned
-     *
-     * @todo This is one among several chicken/egg problems encountered trying to
-     * support state initialization in which some aspects of the state derive from
-     * other aspects of it. It would be nice to dispense with this entirely. But
-     * if it must persist, we should also consider replacing the method with a
-     * direct accessor once state initialization completes, so the initialized
-     * check is only called until it becomes impertinent.
+     * @package Exposed on every node type to facilitate inheritance, as well as
+     * conditional behavior for value nodes.
+     */
+    abstract readonly hasReadonlyAncestor: Accessor<boolean>;
+    /**
+     * @package Exposed on every node type to facilitate inheritance, as well as
+     * conditional behavior for value nodes.
      */
-    protected getInitializedState<K extends keyof EngineState<Spec>>(key: K, options: InitializedStateOptions<EngineState<Spec>, K>): EngineState<Spec>[K];
+    abstract readonly isReadonly: Accessor<boolean>;
     /**
      * @package Exposed on every node type to facilitate inheritance, as well as
      * conditional behavior for value nodes.
      */
-    get isReadonly(): boolean;
+    abstract readonly hasNonRelevantAncestor: Accessor<boolean>;
     /**
      * @package Exposed on every node type to facilitate inheritance, as well as
      * conditional behavior for value nodes.
      */
-    get isRelevant(): boolean;
+    abstract readonly isRelevant: Accessor<boolean>;
     readonly nodeId: NodeID;
     abstract readonly nodeType: InstanceNodeType;
+    abstract readonly appearances: NodeAppearances<Definition>;
     abstract readonly currentState: InstanceNodeCurrentState<Spec, Child>;
+    abstract readonly validationState: NodeValidationState;
     abstract readonly root: Root;
     abstract readonly evaluator: XFormsXPathEvaluator;
     readonly scope: ReactiveScope;
-    get contextReference(): string;
+    readonly computeReference: ComputeInstanceNodeReference;
+    protected readonly computeChildStepReference: ComputeInstanceNodeReference;
+    readonly contextReference: () => string;
     abstract readonly contextNode: Element;
-    constructor(engineConfig: InstanceConfig, parent: AnyParentNode | null, definition: Definition);
+    constructor(engineConfig: InstanceConfig, parent: AnyParentNode | null, definition: Definition, options?: InstanceNodeOptions);
     /**
      * @package This presently serves a few internal use cases, where certain
      * behaviors depend on arbitrary traversal from any point in the instance
@@ -95,9 +95,8 @@ export declare abstract class InstanceNode<Definition extends AnyNodeDefinition,
      * interface for those internal uses.
      */
     abstract getChildren(this: AnyInstanceNode): readonly AnyChildNode[];
-    protected abstract computeReference(parent: AnyInstanceNode | null, definition: Definition): string;
-    getNodeByReference(this: AnyNode, visited: WeakSet<AnyNode>, dependencyReference: string): SubscribableDependency | null;
-    getSubscribableDependencyByReference(this: AnyNode, reference: string): SubscribableDependency | null;
+    getNodesByReference(this: AnyNode, visited: WeakSet<AnyNode>, dependencyReference: string): readonly SubscribableDependency[];
+    getSubscribableDependenciesByReference(this: AnyNode, reference: string): readonly SubscribableDependency[];
     /**
      * This is a default implementation suitable for most node types. The rest
      * (currently: `Root`, `RepeatRange`, `RepeatInstance`) should likely extend

package/dist/instance/hierarchy.d.ts

@@ -1,13 +1,18 @@
 import { Group } from './Group.ts';
-import { RepeatInstance } from './RepeatInstance.ts';
-import { RepeatRange } from './RepeatRange.ts';
+import { ModelValue } from './ModelValue.ts';
+import { Note } from './Note.ts';
+import { RepeatInstance } from './repeat/RepeatInstance.ts';
+import { RepeatRangeControlled } from './repeat/RepeatRangeControlled.ts';
+import { RepeatRangeUncontrolled } from './repeat/RepeatRangeUncontrolled.ts';
 import { Root } from './Root.ts';
 import { SelectField } from './SelectField.ts';
 import { StringField } from './StringField.ts';
 import { Subtree } from './Subtree.ts';
 
-export type AnyNode = Root | Group | Subtree | RepeatRange | RepeatInstance | StringField | SelectField;
+export type RepeatRange = RepeatRangeControlled | RepeatRangeUncontrolled;
+export type AnyNode = Root | Group | Subtree | RepeatRange | RepeatInstance | Note | ModelValue | StringField | SelectField;
 export type AnyParentNode = Root | Group | Subtree | RepeatRange | RepeatInstance;
 export type GeneralParentNode = Root | Group | Subtree | RepeatInstance;
-export type AnyChildNode = Group | Subtree | RepeatRange | RepeatInstance | StringField | SelectField;
-export type GeneralChildNode = Group | Subtree | RepeatRange | StringField | SelectField;
+export type AnyChildNode = Group | Subtree | RepeatRange | RepeatInstance | ModelValue | Note | StringField | SelectField;
+export type GeneralChildNode = Group | Subtree | RepeatRange | ModelValue | Note | StringField | SelectField;
+export type AnyValueNode = ModelValue | Note | StringField | SelectField;

package/dist/instance/internal-api/EvaluationContext.d.ts

@@ -1,4 +1,5 @@
 import { XFormsXPathEvaluator } from '@getodk/xpath';
+import { Accessor } from 'solid-js';
 import { ReactiveScope } from '../../lib/reactivity/scope.ts';
 import { SubscribableDependency } from './SubscribableDependency.ts';
 import { TranslationContext } from './TranslationContext.ts';
@@ -25,11 +26,11 @@ export interface EvaluationContext {
      * Produces the current absolute reference to the {@link contextNode}, where
      * the absolute `/` resolves to the active form state's primary instance root.
      */
-    get contextReference(): string;
+    readonly contextReference: Accessor<string>;
     readonly contextNode: Node;
     /**
-     * Resolves a nodeset reference, possibly relative to the
-     * {@link EvaluationContext.contextNode}.
+     * Resolves nodes corresponding to the provided node-set reference, possibly
+     * relative to the {@link EvaluationContext.contextNode}.
      */
-    readonly getSubscribableDependencyByReference: (reference: string) => SubscribableDependency | null;
+    getSubscribableDependenciesByReference(reference: string): readonly SubscribableDependency[];
 }

package/dist/instance/internal-api/ValidationContext.d.ts

@@ -0,0 +1,21 @@
+import { BindComputation } from '../../model/BindComputation.ts';
+import { MessageDefinition } from '../../parse/text/MessageDefinition.ts';
+import { EvaluationContext } from './EvaluationContext.ts';
+import { SubscribableDependency } from './SubscribableDependency.ts';
+
+interface ValidationContextDefinitionBind {
+    readonly constraint: BindComputation<'constraint'>;
+    readonly constraintMsg: MessageDefinition<'constraintMsg'> | null;
+    readonly required: BindComputation<'required'>;
+    readonly requiredMsg: MessageDefinition<'requiredMsg'> | null;
+}
+interface ValidationContextDefinition {
+    readonly bind: ValidationContextDefinitionBind;
+}
+export interface ValidationContext extends EvaluationContext, SubscribableDependency {
+    readonly definition: ValidationContextDefinition;
+    isRelevant(): boolean;
+    isRequired(): boolean;
+    isBlank(): boolean;
+}
+export {};

package/dist/instance/internal-api/ValueContext.d.ts

@@ -15,8 +15,8 @@ export interface ValueContext<RuntimeValue> extends EvaluationContext {
     readonly scope: ReactiveScope;
     readonly definition: ValueContextDefinition;
     readonly contextNode: Element;
-    get isReadonly(): boolean;
-    get isRelevant(): boolean;
+    isReadonly(): boolean;
+    isRelevant(): boolean;
     readonly encodeValue: (this: unknown, runtimeValue: RuntimeValue) => InstanceValue;
     readonly decodeValue: (this: unknown, instanceValue: InstanceValue) => RuntimeValue;
 }