@getodk/xforms-engine 0.1.1 → 0.3.0

package/dist/instance/repeat/BaseRepeatRange.d.ts

@@ -0,0 +1,160 @@
+import { Accessor } from 'solid-js';
+import { NodeAppearances } from '../../client/NodeAppearances.ts';
+import { BaseRepeatRangeNode } from '../../client/repeat/BaseRepeatRangeNode.ts';
+import { TextRange } from '../../client/TextRange.ts';
+import { AncestorNodeValidationState } from '../../client/validation.ts';
+import { ChildrenState } from '../../lib/reactivity/createChildrenState.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';
+import { SharedNodeState } from '../../lib/reactivity/node-state/createSharedNodeState.ts';
+import { AnyRepeatRangeDefinition, ControlledRepeatRangeDefinition } from '../../model/RepeatRangeDefinition.ts';
+import { DescendantNodeParent, DescendantNodeSharedStateSpec, DescendantNode } from '../abstract/DescendantNode.ts';
+import { NodeID } from '../identity.ts';
+import { EvaluationContext } from '../internal-api/EvaluationContext.ts';
+import { SubscribableDependency } from '../internal-api/SubscribableDependency.ts';
+import { RepeatInstance, RepeatDefinition } from './RepeatInstance.ts';
+
+interface RepeatRangeStateSpec extends DescendantNodeSharedStateSpec {
+    readonly hint: null;
+    readonly label: Accessor<TextRange<'label'> | null>;
+    readonly children: Accessor<readonly NodeID[]>;
+    readonly valueOptions: null;
+    readonly value: null;
+}
+type BaseRepeatRangeNodeType<Definition extends AnyRepeatRangeDefinition> = Definition extends ControlledRepeatRangeDefinition ? 'repeat-range:controlled' : 'repeat-range:uncontrolled';
+export declare abstract class BaseRepeatRange<Definition extends AnyRepeatRangeDefinition> extends DescendantNode<Definition, RepeatRangeStateSpec, RepeatInstance> implements BaseRepeatRangeNode, EvaluationContext, SubscribableDependency {
+    /**
+     * A repeat range doesn't have a corresponding primary instance element of its
+     * own, and its instances are appended to the range's parent element. During
+     * creation of the initial primary instance state and DOM trees, we _could_
+     * reliably append all of the range's instances in order as the definition
+     * tree is recursed. But that would fail to handle some instance addition
+     * cases afterwards.
+     *
+     * Most notably, we need to know where in the primary instance tree to append
+     * instances created for a range which is currently empty. As a lucky
+     * coincidence, this need coincides with the ability to add instances at any
+     * arbitrary index within the range. In each case, we can reference a primary
+     * instance DOM node which will become the new instance's preceding sibling.
+     * Where the range is empty, we use this {@link Comment} node (itself created
+     * and appended during range initialization) in lieu of a nonexistent
+     * preceding instance's {@link contextNode}.
+     *
+     * @todo We likely want to remove these during submission serialization.
+     * @todo Can we use a
+     * {@link https://developer.mozilla.org/en-US/docs/Web/API/Range | DOM Range}
+     * instead?
+     */
+    protected readonly anchorNode: Comment;
+    protected readonly childrenState: ChildrenState<RepeatInstance>;
+    /**
+     * Provides an {@link EvaluationContext} from which to evaluate expressions
+     * where some LocationPath sub-expressions may be **relative to the repeat
+     * range itself**. This is useful for evaluation of expressions where:
+     *
+     * - the expression is typically contextualized to any of its
+     *   {@link RepeatInstance} children, but it presently has none (i.e.
+     *   `relevant`)
+     *
+     * - the expression is conceptually intended to be evaluated in the context of
+     *   the repeat range itself (i.e. `jr:count`)
+     */
+    protected readonly selfEvaluationContext: EvaluationContext & {
+        readonly contextNode: Comment;
+    };
+    /**
+     * @see {@link isSelfRelevant}
+     */
+    protected readonly isEmptyRangeSelfRelevant: Accessor<boolean>;
+    protected readonly state: SharedNodeState<RepeatRangeStateSpec>;
+    protected engineState: EngineState<RepeatRangeStateSpec>;
+    /**
+     * @todo Should we special case repeat `readonly` state the same way
+     * we do for `relevant`?
+     *
+     * @see {@link isSelfRelevant}
+     */
+    isSelfReadonly: Accessor<boolean>;
+    /**
+     * A repeat range does not exist in the primary instance tree. A `relevant`
+     * expression applies to each {@link RepeatInstance} child of the repeat
+     * range. Determining whether a repeat range itself "is relevant" isn't a
+     * concept the spec addresses, but it may be used by clients to determine
+     * whether to allow interaction with the range (e.g. by adding a repeat
+     * instance, or presenting the range's label when empty).
+     *
+     * As a naive first pass, it seems like the heuristic for this should be:
+     *
+     * 1. Does the repeat range have any repeat instance children?
+     *
+     *     - If yes, go to 2.
+     *     - If no, go to 3.
+     *
+     * 2. Does one or more of those children return `true` for the node's
+     *    `relevant` expression (i.e. is the repeat instance "self relevant")?
+     *
+     * 3. Does the relevant expression return `true` for the repeat range itself
+     *    (where, at least for now, the context of that evaluation would be the
+     *    repeat range's {@link anchorNode} to ensure correct relative expressions
+     *    resolve correctly)?
+     *
+     * @todo While (3) is proactively implemented, there isn't presently a test
+     * exercising it. It felt best for now to surface this for discussion in
+     * review to validate that it's going in the right direction.
+     *
+     * @todo While (2) **is actually tested**, the tests currently in place behave
+     * the same way with only the logic for (3), regardless of whether the repeat
+     * range actually has any repeat instance children. It's unclear (a) if that's
+     * a preferable simplification and (b) how that might affect performance (in
+     * theory it could vary depending on form structure and runtime state).
+     */
+    readonly isSelfRelevant: Accessor<boolean>;
+    abstract readonly nodeType: BaseRepeatRangeNodeType<Definition>;
+    /**
+     * @todo RepeatRange*, RepeatInstance* (and RepeatTemplate*) all share the
+     * same body element, and thus all share the same definition `bodyElement`. As
+     * such, they also all share the same `appearances`. At time of writing,
+     * `web-forms` (Vue UI package) treats a `RepeatRangeNode`...
+     *
+     * - ... as a group, if the node has a label (i.e.
+     *   `<group><label/><repeat/></group>`)
+     * - ... effectively as a fragment containing only its instances, otherwise
+     *
+     * We now collapse `<group><repeat>` into `<repeat>`, and no longer treat
+     * "repeat group" as a concept (after parsing). According to the spec, these
+     * appearances **are supposed to** come from that "repeat group" in the form
+     * definition. In practice, many forms do define appearances directly on a
+     * repeat element. The engine currently produces an error if both are defined
+     * simultaneously, but otherwise makes no distinction between appearances in
+     * these form definition shapes:
+     *
+     * ```xml
+     * <group ref="/data/rep1" appearance="...">
+     *   <repeat nodeset="/data/rep1"/>
+     * </group>
+     *
+     * <group ref="/data/rep1">
+     *   <repeat nodeset="/data/rep1"/ appearance="...">
+     * </group>
+     *
+     * <repeat nodeset="/data/rep1"/ appearance="...">
+     * ```
+     *
+     * All of the above creates considerable ambiguity about where "repeat
+     * appearances" should apply, under which circumstances.
+     */
+    abstract readonly appearances: NodeAppearances<Definition>;
+    readonly currentState: MaterializedChildren<CurrentState<RepeatRangeStateSpec>, RepeatInstance>;
+    abstract readonly validationState: AncestorNodeValidationState;
+    constructor(parent: DescendantNodeParent<Definition>, definition: Definition);
+    protected getLastIndex(): number;
+    protected initializeContextNode(parentContextNode: Element): Element;
+    getInstanceIndex(instance: RepeatInstance): number;
+    private createChildren;
+    protected addChildren(afterIndex: number, definitions: readonly RepeatDefinition[]): readonly RepeatInstance[];
+    protected removeChildren(startIndex: number, count: number): readonly RepeatInstance[];
+    subscribe(): void;
+    getChildren(): readonly RepeatInstance[];
+}
+export {};

package/dist/instance/{RepeatInstance.d.ts → repeat/RepeatInstance.d.ts}

@@ -1,16 +1,16 @@
 import { Accessor } from 'solid-js';
-import { RepeatDefinition, RepeatInstanceNode } from '../client/RepeatInstanceNode.ts';
-import { TextRange } from '../index.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';
-import { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
-import { RepeatRange } from './RepeatRange.ts';
-import { DescendantNodeSharedStateSpec, DescendantNode } from './abstract/DescendantNode.ts';
-import { AnyChildNode, GeneralChildNode } from './hierarchy.ts';
-import { NodeID } from './identity.ts';
-import { EvaluationContext } from './internal-api/EvaluationContext.ts';
-import { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
+import { RepeatDefinition, RepeatInstanceNode, RepeatInstanceNodeAppearances } from '../../client/repeat/RepeatInstanceNode.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';
+import { SharedNodeState } from '../../lib/reactivity/node-state/createSharedNodeState.ts';
+import { DescendantNodeSharedStateSpec, DescendantNode } from '../abstract/DescendantNode.ts';
+import { AnyChildNode, GeneralChildNode, RepeatRange } from '../hierarchy.ts';
+import { NodeID } from '../identity.ts';
+import { EvaluationContext } from '../internal-api/EvaluationContext.ts';
+import { SubscribableDependency } from '../internal-api/SubscribableDependency.ts';
 
 export type { RepeatDefinition };
 interface RepeatInstanceStateSpec extends DescendantNodeSharedStateSpec {
@@ -30,10 +30,35 @@ export declare class RepeatInstance extends DescendantNode<RepeatDefinition, Rep
     private readonly currentIndex;
     protected readonly state: SharedNodeState<RepeatInstanceStateSpec>;
     protected engineState: EngineState<RepeatInstanceStateSpec>;
+    /**
+     * @todo Should we special case repeat `readonly` inheritance the same way
+     * we do for `relevant`?
+     *
+     * @see {@link hasNonRelevantAncestor}
+     */
+    readonly hasReadonlyAncestor: Accessor<boolean>;
+    /**
+     * A repeat instance can inherit non-relevance, just like any other node. That
+     * inheritance is derived from the repeat instance's parent node in the
+     * primary instance XML/DOM tree (and would be semantically expected to do so
+     * even if we move away from that implementation detail).
+     *
+     * Since {@link RepeatInstance.parent} is a {@link RepeatRange}, which is a
+     * runtime data model fiction that does not exist in that hierarchy, we pass
+     * this call through, allowing the {@link RepeatRange} to check the actual
+     * primary instance parent node's relevance state.
+     *
+     * @todo Should we apply similar reasoning in {@link hasReadonlyAncestor}?
+     */
+    readonly hasNonRelevantAncestor: Accessor<boolean>;
     readonly nodeType = "repeat-instance";
+    /**
+     * @see {@link RepeatRange.appearances}
+     */
+    readonly appearances: RepeatInstanceNodeAppearances;
     readonly currentState: MaterializedChildren<CurrentState<RepeatInstanceStateSpec>, GeneralChildNode>;
+    readonly validationState: AncestorNodeValidationState;
     constructor(parent: RepeatRange, definition: RepeatDefinition, options: RepeatInstanceOptions);
-    protected computeReference(parent: RepeatRange): string;
     protected initializeContextNode(parentContextNode: Element, nodeName: string): Element;
     subscribe(): void;
     getChildren(): readonly GeneralChildNode[];

package/dist/instance/repeat/RepeatRangeControlled.d.ts

@@ -0,0 +1,16 @@
+import { RepeatRangeNodeAppearances } from '../../client/repeat/BaseRepeatRangeNode.ts';
+import { RepeatRangeControlledNode } from '../../client/repeat/RepeatRangeControlledNode.ts';
+import { AncestorNodeValidationState } from '../../client/validation.ts';
+import { ControlledRepeatRangeDefinition } from '../../model/RepeatRangeDefinition.ts';
+import { GeneralParentNode } from '../hierarchy.ts';
+import { EvaluationContext } from '../internal-api/EvaluationContext.ts';
+import { SubscribableDependency } from '../internal-api/SubscribableDependency.ts';
+import { BaseRepeatRange } from './BaseRepeatRange.ts';
+
+export declare class RepeatRangeControlled extends BaseRepeatRange<ControlledRepeatRangeDefinition> implements RepeatRangeControlledNode, EvaluationContext, SubscribableDependency {
+    readonly nodeType = "repeat-range:controlled";
+    readonly appearances: RepeatRangeNodeAppearances;
+    readonly validationState: AncestorNodeValidationState;
+    constructor(parent: GeneralParentNode, definition: ControlledRepeatRangeDefinition);
+    private initializeControlledChildrenState;
+}

package/dist/instance/repeat/RepeatRangeUncontrolled.d.ts

@@ -0,0 +1,35 @@
+import { RepeatRangeNodeAppearances } from '../../client/repeat/BaseRepeatRangeNode.ts';
+import { RepeatRangeUncontrolledNode } from '../../client/repeat/RepeatRangeUncontrolledNode.ts';
+import { AncestorNodeValidationState } from '../../client/validation.ts';
+import { UncontrolledRepeatRangeDefinition } from '../../model/RepeatRangeDefinition.ts';
+import { GeneralParentNode } from '../hierarchy.ts';
+import { EvaluationContext } from '../internal-api/EvaluationContext.ts';
+import { SubscribableDependency } from '../internal-api/SubscribableDependency.ts';
+import { Root } from '../Root.ts';
+import { BaseRepeatRange } from './BaseRepeatRange.ts';
+
+export declare class RepeatRangeUncontrolled extends BaseRepeatRange<UncontrolledRepeatRangeDefinition> implements RepeatRangeUncontrolledNode, EvaluationContext, SubscribableDependency {
+    readonly nodeType = "repeat-range:uncontrolled";
+    readonly appearances: RepeatRangeNodeAppearances;
+    readonly validationState: AncestorNodeValidationState;
+    constructor(parent: GeneralParentNode, definition: UncontrolledRepeatRangeDefinition);
+    addInstances(afterIndex?: number, count?: number): Root;
+    /**
+     * Removes the {@link RepeatInstance}s corresponding to the specified range of
+     * indexes, and then removes those repeat instances from the repeat range's
+     * own children state in that order:
+     *
+     * 1. Identify the set of {@link RepeatInstance}s to be removed.
+     *
+     * 2. For each {@link RepeatInstance} pending removal, perform that node's
+     *    removal logic. @see {@link RepeatInstance.remove} for more detail.
+     *
+     * 3. Finalize update to the repeat range's own {@link childrenState},
+     *    omitting those {@link RepeatInstance}s which were removed.
+     *
+     * This ordering ensures a consistent representation of state is established
+     * prior to any downstream reactive updates, and ensures that removed nodes'
+     * reactivity is cleaned up.
+     */
+    removeInstances(startIndex: number, count?: number): Root;
+}

package/dist/instance/text/TextRange.d.ts

@@ -1,11 +1,11 @@
-import { TextRange as ClientTextRange, TextChunk } from '../../client/TextRange.ts';
+import { TextRange as ClientTextRange, TextChunk, TextOrigin, TextRole } from '../../client/TextRange.ts';
 
-export type TextRole = 'hint' | 'label';
-export declare class TextRange<Role extends TextRole> implements ClientTextRange<Role> {
+export declare class TextRange<Role extends TextRole, Origin extends TextOrigin> implements ClientTextRange<Role, Origin> {
+    readonly origin: Origin;
     readonly role: Role;
     protected readonly chunks: readonly TextChunk[];
     [Symbol.iterator](): Generator<TextChunk, void, undefined>;
     get formatted(): Record<PropertyKey, unknown>;
     get asString(): string;
-    constructor(role: Role, chunks: readonly TextChunk[]);
+    constructor(origin: Origin, role: Role, chunks: readonly TextChunk[]);
 }

package/dist/lib/TokenListParser.d.ts

@@ -0,0 +1,84 @@
+import { PartiallyKnownString } from '../../../common/types/string/PartiallyKnownString.ts';
+
+type SymbolIterator = typeof Symbol.iterator;
+type TokenListKey<CanonicalToken extends string> = PartiallyKnownString<CanonicalToken> | SymbolIterator;
+type TokenListIterator<CanonicalToken extends string> = IterableIterator<PartiallyKnownString<CanonicalToken>>;
+/**
+ * @see {@link TokenListParser}
+ */
+export type TokenList<CanonicalToken extends string = string> = {
+    readonly [Key in TokenListKey<CanonicalToken>]: Key extends SymbolIterator ? () => TokenListIterator<CanonicalToken> : boolean;
+};
+interface TokenListAlias<CanonicalToken extends string> {
+    readonly fromAlias: string;
+    readonly toCanonical: CanonicalToken;
+}
+type TokenAliases<CanonicalToken extends string> = ReadonlyArray<TokenListAlias<CanonicalToken>>;
+interface TokenListParserOptions<CanonicalToken extends string> {
+    readonly aliases?: TokenAliases<CanonicalToken>;
+}
+type TokenListAttributeName = PartiallyKnownString<'appearance' | 'class'>;
+/**
+ * Intended primarily for use in parsing these features:
+ *
+ * - {@link https://getodk.github.io/xforms-spec/#appearances | appearances} ({@link https://xlsform.org/en/#appearance | additional documentation})
+ *
+ * - {@link https://getodk.github.io/xforms-spec/#body-attributes | body `class` attribute}
+ *
+ * This class is named as a reference to {@link DOMTokenList}
+ * ({@link https://developer.mozilla.org/en-US/docs/Web/API/DOMTokenList | MDN}),
+ * with these similarities:
+ *
+ * - Represents a value whose serialization is a space-separated list.
+ * - Each member ("token") is a string (without whitespace).
+ * - Provides set-like semantics to determine presence of members.
+ * - Provides ordering semantics as determined by the serialization.
+ *
+ * This class differs from that prior art in that:
+ *
+ * - It provides a notion of "canonical" members. This is _mostly_ (but not
+ *   entirely) intended as a convenience to client developers, automatically
+ *   populating canonical/known tokens for a given parser type in
+ *   editor-provided autocomplete, etc. **Importantly**, non-canonical tokens
+ *   _are not ignored_ in either the {@link TokenList}'s types or runtime
+ *   values.
+ *
+ * - Provided "canonical" members may also be used to specify
+ *   {@link TokenListParserOptions.aliases | optional aliases}. (Example: when
+ *   parsing "appearances", an alias might map an older deprecated appearance to
+ *   a newer canonical equivalent.) **Importantly**, when a token matches an
+ *   alias, both that alias _and the token as-specified_ will be present in the
+ *   produced {@link TokenList}.
+ *
+ * - As a parser, it is intended to be read-only. The serialized format which it
+ *   parses is _generally_ the source of truth (excepting e.g. aliases).
+ *   Notably, and as mentioned above, ordering is determined by:
+ *
+ *     - Iterating each member, as provided by the serialized representation
+ *
+ *     - If that member corresponds to an alias, that alias is yielded first
+ *
+ *     - Regardless of whether the member corresponds to an alias, the member is
+ *       yielded as-specified
+ *
+ * - A parsed {@link TokenList} is intended to maximize convenience of read-only
+ *   access. Despite many _conceptual similarities_, most of the
+ *   {@link DOMTokenList} **interface** is eschewed in favor of two (mutually
+ *   equivalent) access mechanisms:
+ *
+ *     - `Iterable<Token>`, with the ordering semantics described above
+ *     - `Record<Token, boolean>`
+ *
+ * \* This may change, as we refine requirements. In the future, we may
+ * introduce a notion of mutually exclusive tokens (e.g. "appearances" which
+ * cannot be used together), which may in turn utilize instance-defined ordering
+ * as part of that mechanism.
+ */
+export declare class TokenListParser<CanonicalToken extends string, TokenAlias extends CanonicalToken = CanonicalToken> {
+    readonly canonicalTokens: readonly CanonicalToken[];
+    private readonly aliases;
+    constructor(canonicalTokens: readonly CanonicalToken[], options?: TokenListParserOptions<TokenAlias>);
+    parseFrom(element: Element, attributeName: TokenListAttributeName): TokenList<CanonicalToken>;
+}
+export type ParsedTokenList<Parser extends TokenListParser<any>> = Parser extends TokenListParser<infer CanonicalToken> ? TokenList<CanonicalToken> : never;
+export {};

package/dist/lib/dom/query.d.ts

@@ -9,6 +9,10 @@ export interface ItemsetElement extends KnownAttributeLocalNamedElement<'itemset
 }
 export interface LabelElement extends LocalNamedElement<'label'> {
 }
+export interface RepeatGroupLabelElement extends LabelElement {
+    getAttribute(name: 'form-definition-source'): 'repeat-group';
+    getAttribute(name: string): string;
+}
 export interface RepeatElement extends KnownAttributeLocalNamedElement<'repeat', 'nodeset'> {
 }
 export interface ValueElement extends LocalNamedElement<'value'> {
@@ -17,5 +21,6 @@ export declare const getHintElement: (parent: Element) => HintElement | null;
 export declare const getItemElements: (parent: SelectElement) => readonly ItemElement[];
 export declare const getItemsetElement: (parent: Element) => ItemsetElement | null;
 export declare const getLabelElement: (parent: Element) => LabelElement | null;
+export declare const getRepeatGroupLabelElement: (parent: Element) => RepeatGroupLabelElement | null;
 export declare const getRepeatElement: (parent: Element) => RepeatElement | null;
 export declare const getValueElement: (parent: ItemElement | ItemsetElement) => ValueElement | null;

package/dist/lib/reactivity/createComputedExpression.d.ts

@@ -1,13 +1,18 @@
 import { Accessor } from 'solid-js';
 import { DependentExpression, DependentExpressionResultType } from '../../expression/DependentExpression.ts';
 import { EvaluationContext } from '../../instance/internal-api/EvaluationContext.ts';
+import { SubscribableDependency } from '../../instance/internal-api/SubscribableDependency.ts';
 
 interface ComputedExpressionResults {
     readonly boolean: boolean;
     readonly nodes: Node[];
+    readonly number: number;
     readonly string: string;
 }
 type EvaluatedExpression<Type extends DependentExpressionResultType> = ComputedExpressionResults[Type];
 type ComputedExpression<Type extends DependentExpressionResultType> = Accessor<EvaluatedExpression<Type>>;
-export declare const createComputedExpression: <Type extends "string" | "boolean" | "nodes">(context: EvaluationContext, dependentExpression: DependentExpression<Type>) => ComputedExpression<Type>;
+interface CreateComputedExpressionOptions {
+    readonly arbitraryDependencies?: readonly SubscribableDependency[];
+}
+export declare const createComputedExpression: <Type extends DependentExpressionResultType>(context: EvaluationContext, dependentExpression: DependentExpression<Type>, options?: CreateComputedExpressionOptions) => ComputedExpression<Type>;
 export {};

package/dist/lib/reactivity/createNoteReadonlyThunk.d.ts

@@ -0,0 +1,5 @@
+import { Accessor } from 'solid-js';
+import { EvaluationContext } from '../../instance/internal-api/EvaluationContext.ts';
+import { BindComputation } from '../../model/BindComputation.ts';
+
+export declare const createNoteReadonlyThunk: (context: EvaluationContext, readonlyDefinition: BindComputation<"readonly">) => Accessor<true>;

package/dist/lib/reactivity/materializeCurrentStateChildren.d.ts

@@ -1,6 +1,7 @@
 import { AnyChildNode } from '../../instance/hierarchy.ts';
 import { NodeID } from '../../instance/identity.ts';
 import { ChildrenState } from './createChildrenState.ts';
+import { ReactiveScope } from './scope.ts';
 
 export interface EncodedParentState {
     readonly children: readonly NodeID[];
@@ -16,4 +17,4 @@ export type MaterializedChildren<BaseState extends EncodedParentState, Child ext
  *
  * @see {@link createChildrenState} for further detail.
  */
-export declare const materializeCurrentStateChildren: <Child extends AnyChildNode, ParentState extends EncodedParentState>(currentState: ParentState, childrenState: ChildrenState<Child>) => MaterializedChildren<ParentState, Child>;
+export declare const materializeCurrentStateChildren: <Child extends AnyChildNode, ParentState extends EncodedParentState>(scope: ReactiveScope, currentState: ParentState, childrenState: ChildrenState<Child>) => MaterializedChildren<ParentState, Child>;

package/dist/lib/reactivity/node-state/createSharedNodeState.d.ts

@@ -16,7 +16,7 @@ export interface SharedNodeState<Spec extends StateSpec> {
     readonly currentState: CurrentState<Spec>;
     readonly setProperty: SetEnginePropertyState<Spec>;
 }
-interface SharedNodeStateOptions<Factory extends OpaqueReactiveObjectFactory, Spec extends StateSpec> {
+export interface SharedNodeStateOptions<Factory extends OpaqueReactiveObjectFactory, Spec extends StateSpec> {
     readonly clientStateFactory: SpecifiedClientStateFactory<Factory, Spec>;
 }
 export declare const createSharedNodeState: <Factory extends OpaqueReactiveObjectFactory, Spec extends StateSpec>(scope: ReactiveScope, spec: Spec, options: SharedNodeStateOptions<Factory, Spec>) => SharedNodeState<Spec>;

package/dist/lib/reactivity/node-state/createSpecifiedState.d.ts

@@ -110,7 +110,7 @@ export type StaticPropertySpec<T> = Exclude<T, NonStaticValue>;
 export type StatePropertySpec<T = any> = MutablePropertySpec<T> | ComputedPropertySpec<T> | StaticPropertySpec<T>;
 export declare const isMutablePropertySpec: <T>(propertySpec: StatePropertySpec<T>) => propertySpec is MutablePropertySpec<T>;
 export declare const isComputedPropertySpec: <T>(propertySpec: StatePropertySpec<T>) => propertySpec is ComputedPropertySpec<T>;
-export declare const isStaticPropertySpec: <T>(propertySpec: StatePropertySpec<T>) => propertySpec is Exclude<T, NonStaticValue>;
+export declare const isStaticPropertySpec: <T>(propertySpec: StatePropertySpec<T>) => propertySpec is StaticPropertySpec<T>;
 export type StateSpec = Record<string, StatePropertySpec>;
 type SpecifiedStatePropertyValue<PropertySpec extends StatePropertySpec> = PropertySpec extends StatePropertySpec<infer T> ? T : never;
 type DerivedMutableKeys<Spec extends StateSpec> = {

package/dist/lib/reactivity/text/createFieldHint.d.ts

@@ -1,6 +1,6 @@
 import { Accessor } from 'solid-js';
+import { TextRange } from '../../../client/TextRange.ts';
 import { EvaluationContext } from '../../../instance/internal-api/EvaluationContext.ts';
-import { TextRange } from '../../../instance/text/TextRange.ts';
-import { ValueNodeDefinition } from '../../../model/ValueNodeDefinition.ts';
+import { LeafNodeDefinition } from '../../../model/LeafNodeDefinition.ts';
 
-export declare const createFieldHint: (context: EvaluationContext, definition: ValueNodeDefinition) => Accessor<TextRange<'hint'> | null>;
+export declare const createFieldHint: (context: EvaluationContext, definition: LeafNodeDefinition) => Accessor<TextRange<"hint", "form"> | null>;

package/dist/lib/reactivity/text/createNodeLabel.d.ts

@@ -1,6 +1,6 @@
 import { Accessor } from 'solid-js';
+import { TextRange } from '../../../client/TextRange.ts';
 import { EvaluationContext } from '../../../instance/internal-api/EvaluationContext.ts';
-import { TextRange } from '../../../instance/text/TextRange.ts';
 import { AnyNodeDefinition } from '../../../model/NodeDefinition.ts';
 
-export declare const createNodeLabel: (context: EvaluationContext, definition: AnyNodeDefinition) => Accessor<TextRange<'label'> | null>;
+export declare const createNodeLabel: (context: EvaluationContext, definition: AnyNodeDefinition) => Accessor<TextRange<"label", "form"> | null>;

package/dist/lib/reactivity/text/createNoteText.d.ts

@@ -0,0 +1,25 @@
+import { Accessor } from 'solid-js';
+import { TextRange } from '../../../client/TextRange.ts';
+import { EvaluationContext } from '../../../instance/internal-api/EvaluationContext.ts';
+import { NoteTextDefinition } from '../../../parse/NoteNodeDefinition.ts';
+
+export type NoteTextRole = 'label' | 'hint';
+export type ComputedNoteText<Role extends NoteTextRole = NoteTextRole> = Accessor<TextRange<Role, 'form'>>;
+interface BaseNoteText {
+    readonly role: NoteTextRole;
+    readonly label: ComputedNoteText<'label'> | null;
+    readonly hint: ComputedNoteText<'hint'> | null;
+}
+interface LabelNoteText extends BaseNoteText {
+    readonly role: 'label';
+    readonly label: ComputedNoteText<'label'>;
+    readonly hint: null;
+}
+interface HintNoteText extends BaseNoteText {
+    readonly role: 'hint';
+    readonly label: null;
+    readonly hint: ComputedNoteText<'hint'>;
+}
+export type NoteTextComputation = LabelNoteText | HintNoteText;
+export declare const createNoteText: (context: EvaluationContext, noteTextDefinition: NoteTextDefinition) => NoteTextComputation;
+export {};

package/dist/lib/reactivity/text/createTextRange.d.ts

@@ -1,12 +1,10 @@
 import { Accessor } from 'solid-js';
-import { TextElementDefinition } from '../../../body/text/TextElementDefinition.ts';
+import { TextRole } from '../../../client/TextRange.ts';
 import { EvaluationContext } from '../../../instance/internal-api/EvaluationContext.ts';
-import { TextRange, TextRole } from '../../../instance/text/TextRange.ts';
+import { TextRange } from '../../../instance/text/TextRange.ts';
+import { TextRangeDefinition } from '../../../parse/text/abstract/TextRangeDefinition.ts';
 
-interface CreateTextRangeOptions<FallbackValue extends string | null> {
-    readonly fallbackValue?: FallbackValue;
-}
-type ComputedTextRange<Role extends TextRole, Definition extends TextElementDefinition<Role> | null, FallbackValue extends string | null> = Accessor<Definition extends null ? FallbackValue extends null ? TextRange<Role> | null : TextRange<Role> : TextRange<Role>>;
+type ComputedFormTextRange<Role extends TextRole> = Accessor<TextRange<Role, 'form'>>;
 /**
  * Creates a text range (e.g. label or hint) from the provided definition,
  * reactive to:
@@ -16,5 +14,5 @@ type ComputedTextRange<Role extends TextRole, Definition extends TextElementDefi
  *
  * @todo This does not yet handle itext translations **with** outputs!
  */
-export declare const createTextRange: <Role extends TextRole, Definition extends TextElementDefinition<Role> | null, FallbackValue extends string | null = null>(context: EvaluationContext, role: Role, definition: Definition, options?: CreateTextRangeOptions<FallbackValue>) => ComputedTextRange<Role, Definition, FallbackValue>;
+export declare const createTextRange: <Role extends TextRole>(context: EvaluationContext, role: Role, definition: TextRangeDefinition<Role>) => ComputedFormTextRange<Role>;
 export {};

package/dist/lib/reactivity/validation/createAggregatedViolations.d.ts

@@ -0,0 +1,9 @@
+import { OpaqueReactiveObjectFactory } from '../../../client/OpaqueReactiveObjectFactory.ts';
+import { AncestorNodeValidationState } from '../../../client/validation.ts';
+import { AnyParentNode } from '../../../instance/hierarchy.ts';
+
+interface AggregatedViolationsOptions {
+    readonly clientStateFactory: OpaqueReactiveObjectFactory<AncestorNodeValidationState>;
+}
+export declare const createAggregatedViolations: (context: AnyParentNode, options: AggregatedViolationsOptions) => AncestorNodeValidationState;
+export {};

package/dist/lib/reactivity/validation/createValidation.d.ts

@@ -0,0 +1,18 @@
+import { Accessor } from 'solid-js';
+import { OpaqueReactiveObjectFactory } from '../../../client/OpaqueReactiveObjectFactory.ts';
+import { AnyViolation, ConditionValidation, ValidationCondition } from '../../../client/validation.ts';
+import { ValidationContext } from '../../../instance/internal-api/ValidationContext.ts';
+import { SharedNodeState, SharedNodeStateOptions } from '../node-state/createSharedNodeState.ts';
+
+type ComputedConditionValidation<Condition extends ValidationCondition> = Accessor<ConditionValidation<Condition>>;
+type ComputedViolation = Accessor<AnyViolation | null>;
+interface ValidationStateSpec {
+    readonly constraint: ComputedConditionValidation<'constraint'>;
+    readonly required: ComputedConditionValidation<'required'>;
+    readonly violation: ComputedViolation;
+}
+export type SharedValidationState = SharedNodeState<ValidationStateSpec>;
+interface ValidationStateOptions<Factory extends OpaqueReactiveObjectFactory> extends SharedNodeStateOptions<Factory, ValidationStateSpec> {
+}
+export declare const createValidationState: <Factory extends OpaqueReactiveObjectFactory>(context: ValidationContext, options: ValidationStateOptions<Factory>) => SharedValidationState;
+export {};

package/dist/model/BindDefinition.d.ts

@@ -1,7 +1,7 @@
 import { XFormDataType } from '../XFormDataType.ts';
 import { XFormDefinition } from '../XFormDefinition.ts';
 import { DependencyContext } from '../expression/DependencyContext.ts';
-import { DependentExpression } from '../expression/DependentExpression.ts';
+import { MessageDefinition } from '../parse/text/MessageDefinition.ts';
 import { BindComputation } from './BindComputation.ts';
 import { BindElement } from './BindElement.ts';
 import { ModelDefinition } from './ModelDefinition.ts';
@@ -21,7 +21,9 @@ export declare class BindDefinition extends DependencyContext {
     /**
      * Diverges from {@link https://github.com/getodk/javarosa/blob/059321160e6f8dbb3e81d9add61d68dd35b13cc8/dag.md | JavaRosa's}, which excludes `constraint` expressions. We compute `constraint` dependencies like the other <bind> computation expressions, but explicitly ignore self-references (this is currently handled by {@link BindComputation}, via its {@link DependentExpression} parent class).
      */
-    readonly constraint: BindComputation<'constraint'> & DependentExpression<'boolean'>;
+    readonly constraint: BindComputation<'constraint'>;
+    readonly constraintMsg: MessageDefinition<'constraintMsg'> | null;
+    readonly requiredMsg: MessageDefinition<'requiredMsg'> | null;
     readonly saveIncomplete: BindComputation<'saveIncomplete'>;
     protected _parentBind: BindDefinition | null | undefined;
     get parentBind(): BindDefinition | null;

package/dist/model/BindElement.d.ts

@@ -3,4 +3,5 @@ export interface BindElement {
     readonly localName: 'bind';
     getAttribute(name: 'nodeset'): BindNodeset;
     getAttribute(name: string): string | null;
+    getAttributeNS(namespaceURI: string | null, localName: string): string | null;
 }

package/dist/model/DescendentNodeDefinition.d.ts

@@ -1,11 +1,10 @@
 import { AnyBodyElementDefinition } from '../body/BodyDefinition.ts';
-import { RepeatDefinition } from '../body/RepeatDefinition.ts';
 import { BindDefinition } from './BindDefinition.ts';
 import { ModelNode, NodeChildren, NodeDefaultValue, NodeDefinition, NodeDefinitionType, NodeInstances, NodeParent } from './NodeDefinition.ts';
 import { RootDefinition } from './RootDefinition.ts';
 
 export type DescendentNodeType = Exclude<NodeDefinitionType, 'root'>;
-type DescendentNodeBodyElement = AnyBodyElementDefinition | RepeatDefinition;
+type DescendentNodeBodyElement = AnyBodyElementDefinition;
 export declare abstract class DescendentNodeDefinition<Type extends DescendentNodeType, BodyElement extends DescendentNodeBodyElement | null = DescendentNodeBodyElement | null> implements NodeDefinition<Type> {
     readonly parent: NodeParent<Type>;
     readonly bind: BindDefinition;

package/dist/model/{ValueNodeDefinition.d.ts → LeafNodeDefinition.d.ts}

@@ -1,12 +1,11 @@
-import { AnyBodyElementDefinition } from '../body/BodyDefinition.ts';
-import { AnyControlDefinition } from '../body/control/ControlDefinition.ts';
+import { AnyBodyElementDefinition, ControlElementDefinition } from '../body/BodyDefinition.ts';
 import { BindDefinition } from './BindDefinition.ts';
 import { DescendentNodeDefinition } from './DescendentNodeDefinition.ts';
 import { NodeDefinition, ParentNodeDefinition } from './NodeDefinition.ts';
 
-export declare class ValueNodeDefinition extends DescendentNodeDefinition<'value-node', AnyControlDefinition | null> implements NodeDefinition<'value-node'> {
+export declare class LeafNodeDefinition extends DescendentNodeDefinition<'leaf-node', ControlElementDefinition | null> implements NodeDefinition<'leaf-node'> {
     readonly node: Element;
-    readonly type = "value-node";
+    readonly type = "leaf-node";
     readonly nodeName: string;
     readonly children: null;
     readonly instances: null;