@getodk/xforms-engine 0.2.0 → 0.3.0

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/{ValueNodeDefinition.d.ts → LeafNodeDefinition.d.ts}

@@ -3,9 +3,9 @@ import { BindDefinition } from './BindDefinition.ts';
 import { DescendentNodeDefinition } from './DescendentNodeDefinition.ts';
 import { NodeDefinition, ParentNodeDefinition } from './NodeDefinition.ts';
 
-export declare class ValueNodeDefinition extends DescendentNodeDefinition<'value-node', ControlElementDefinition | 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;

package/dist/model/NodeDefinition.d.ts

@@ -1,12 +1,12 @@
 import { AnyBodyElementDefinition } from '../body/BodyDefinition.ts';
 import { RepeatElementDefinition } from '../body/RepeatElementDefinition.ts';
 import { BindDefinition } from './BindDefinition.ts';
+import { LeafNodeDefinition } from './LeafNodeDefinition.ts';
 import { RepeatInstanceDefinition } from './RepeatInstanceDefinition.ts';
-import { RepeatRangeDefinition } from './RepeatRangeDefinition.ts';
+import { AnyRepeatRangeDefinition } from './RepeatRangeDefinition.ts';
 import { RepeatTemplateDefinition } from './RepeatTemplateDefinition.ts';
 import { RootDefinition } from './RootDefinition.ts';
 import { SubtreeDefinition } from './SubtreeDefinition.ts';
-import { ValueNodeDefinition } from './ValueNodeDefinition.ts';
 
 /**
  * Corresponds to the model/entry DOM root node, i.e.:
@@ -44,16 +44,16 @@ export type SubtreeNodeType = 'subtree';
  * - An element with no child elements
  * - Any attribute corresponding to a bind's `nodeset` expression
  */
-export type ValueNodeType = 'value-node';
-export type NodeDefinitionType = RootNodeType | RepeatRangeType | RepeatTemplateType | RepeatInstanceType | SubtreeNodeType | ValueNodeType;
+export type LeafNodeType = 'leaf-node';
+export type NodeDefinitionType = RootNodeType | RepeatRangeType | RepeatTemplateType | RepeatInstanceType | SubtreeNodeType | LeafNodeType;
 export type ParentNodeDefinition = RootDefinition | RepeatTemplateDefinition | RepeatInstanceDefinition | SubtreeDefinition;
-export type ChildNodeDefinition = RepeatRangeDefinition | SubtreeDefinition | ValueNodeDefinition;
-export type ChildNodeInstanceDefinition = RepeatTemplateDefinition | RepeatInstanceDefinition | SubtreeDefinition | ValueNodeDefinition;
+export type ChildNodeDefinition = AnyRepeatRangeDefinition | LeafNodeDefinition | SubtreeDefinition;
+export type ChildNodeInstanceDefinition = RepeatTemplateDefinition | RepeatInstanceDefinition | SubtreeDefinition | LeafNodeDefinition;
 export type NodeChildren<Type extends NodeDefinitionType> = Type extends ParentNodeDefinition['type'] ? readonly ChildNodeDefinition[] : null;
 export type NodeInstances<Type extends NodeDefinitionType> = Type extends 'repeat-range' ? readonly RepeatInstanceDefinition[] : null;
 export type NodeParent<Type extends NodeDefinitionType> = Type extends ChildNodeDefinition['type'] | ChildNodeInstanceDefinition['type'] ? ParentNodeDefinition : null;
 export type ModelNode<Type extends NodeDefinitionType> = Type extends 'repeat-range' ? null : Element;
-export type NodeDefaultValue<Type extends NodeDefinitionType> = Type extends 'value-node' ? string : null;
+export type NodeDefaultValue<Type extends NodeDefinitionType> = Type extends 'leaf-node' ? string : null;
 export interface NodeDefinition<Type extends NodeDefinitionType> {
     readonly type: Type;
     readonly bind: BindDefinition;
@@ -69,7 +69,7 @@ export interface NodeDefinition<Type extends NodeDefinitionType> {
     readonly node: ModelNode<Type>;
     readonly defaultValue: NodeDefaultValue<Type>;
 }
-export type AnyNodeDefinition = RootDefinition | RepeatRangeDefinition | RepeatTemplateDefinition | RepeatInstanceDefinition | SubtreeDefinition | ValueNodeDefinition;
+export type AnyNodeDefinition = RootDefinition | AnyRepeatRangeDefinition | RepeatTemplateDefinition | RepeatInstanceDefinition | SubtreeDefinition | LeafNodeDefinition;
 export type TypedNodeDefinition<Type> = Extract<AnyNodeDefinition, {
     readonly type: Type;
 }>;

package/dist/model/RepeatInstanceDefinition.d.ts

@@ -1,7 +1,7 @@
 import { RepeatElementDefinition } from '../body/RepeatElementDefinition.ts';
 import { DescendentNodeDefinition } from './DescendentNodeDefinition.ts';
 import { ChildNodeDefinition, NodeDefinition } from './NodeDefinition.ts';
-import { RepeatRangeDefinition } from './RepeatRangeDefinition.ts';
+import { AnyRepeatRangeDefinition } from './RepeatRangeDefinition.ts';
 
 export declare class RepeatInstanceDefinition extends DescendentNodeDefinition<'repeat-instance', RepeatElementDefinition> implements NodeDefinition<'repeat-instance'> {
     readonly node: Element;
@@ -10,6 +10,6 @@ export declare class RepeatInstanceDefinition extends DescendentNodeDefinition<'
     readonly children: readonly ChildNodeDefinition[];
     readonly instances: null;
     readonly defaultValue: null;
-    constructor(range: RepeatRangeDefinition, node: Element);
+    constructor(range: AnyRepeatRangeDefinition, node: Element);
     toJSON(): Omit<this, "toJSON" | "parent" | "bind" | "root" | "bodyElement">;
 }

package/dist/model/RepeatRangeDefinition.d.ts

@@ -1,20 +1,30 @@
 import { RepeatElementDefinition } from '../body/RepeatElementDefinition.ts';
+import { RepeatCountControlExpression } from '../parse/expression/RepeatCountControlExpression.ts';
 import { BindDefinition } from './BindDefinition.ts';
 import { DescendentNodeDefinition } from './DescendentNodeDefinition.ts';
 import { NodeDefinition, ParentNodeDefinition } from './NodeDefinition.ts';
 import { RepeatInstanceDefinition } from './RepeatInstanceDefinition.ts';
 import { RepeatTemplateDefinition } from './RepeatTemplateDefinition.ts';
 
+export interface ControlledRepeatRangeDefinition extends RepeatRangeDefinition {
+    readonly count: RepeatCountControlExpression;
+}
+export interface UncontrolledRepeatRangeDefinition extends RepeatRangeDefinition {
+    readonly count: null;
+}
+export type AnyRepeatRangeDefinition = ControlledRepeatRangeDefinition | UncontrolledRepeatRangeDefinition;
 export declare class RepeatRangeDefinition extends DescendentNodeDefinition<'repeat-range', RepeatElementDefinition> implements NodeDefinition<'repeat-range'> {
-    static createTemplateElement(instanceElement: Element): Element;
-    static createInstanceElement(templateElement: Element): Element;
+    static from(parent: ParentNodeDefinition, bind: BindDefinition, bodyElement: RepeatElementDefinition, modelNodes: readonly [Element, ...Element[]]): AnyRepeatRangeDefinition;
     readonly type = "repeat-range";
     readonly template: RepeatTemplateDefinition;
     readonly children: null;
     readonly instances: RepeatInstanceDefinition[];
+    readonly count: RepeatCountControlExpression | null;
     readonly node: null;
     readonly nodeName: string;
     readonly defaultValue: null;
-    constructor(parent: ParentNodeDefinition, bind: BindDefinition, bodyElement: RepeatElementDefinition, modelNodes: readonly [Element, ...Element[]]);
-    toJSON(): Omit<this, "toJSON" | "parent" | "bind" | "root" | "bodyElement">;
+    private constructor();
+    isControlled(): this is ControlledRepeatRangeDefinition;
+    isUncontrolled(): this is UncontrolledRepeatRangeDefinition;
+    toJSON(): Omit<this, "toJSON" | "parent" | "bind" | "root" | "bodyElement" | "isControlled" | "isUncontrolled">;
 }

package/dist/parse/NoteNodeDefinition.d.ts

@@ -0,0 +1,31 @@
+import { AnyBodyElementDefinition } from '../body/BodyDefinition.ts';
+import { InputDefinition } from '../body/control/InputDefinition.ts';
+import { ConstantTruthyDependentExpression } from '../expression/DependentExpression.ts';
+import { BindComputation } from '../model/BindComputation.ts';
+import { BindDefinition } from '../model/BindDefinition.ts';
+import { LeafNodeDefinition } from '../model/LeafNodeDefinition.ts';
+import { ParentNodeDefinition } from '../model/NodeDefinition.ts';
+import { HintDefinition } from './text/HintDefinition.ts';
+import { LabelDefinition } from './text/LabelDefinition.ts';
+
+export type NoteReadonlyDefinition = BindComputation<'readonly'> & ConstantTruthyDependentExpression;
+export interface NoteBindDefinition extends BindDefinition {
+    readonly readonly: NoteReadonlyDefinition;
+}
+export type NoteTextDefinition = LabelDefinition | HintDefinition;
+/**
+ * @package This class is used internally, both in static types and at runtime,
+ * to guard and guide the distinction between instance state nodes for 'note'
+ * and 'string' node types. It is intentionally package-private! The less
+ * specific {@link NoteNode.definition} type, if it has any client value at all,
+ * should be more than sufficient. Clients are otherwise expected to use other
+ * aspects of the node's interface (such as its {@link NoteNode.nodeType} and
+ * distinct {@link NoteNode.currentState} types) to handle note-specific logic.
+ */
+export declare class NoteNodeDefinition extends LeafNodeDefinition {
+    readonly bind: NoteBindDefinition;
+    readonly bodyElement: InputDefinition;
+    readonly noteTextDefinition: NoteTextDefinition;
+    static from(parent: ParentNodeDefinition, bind: BindDefinition, bodyElement: AnyBodyElementDefinition | null, node: Element): NoteNodeDefinition | null;
+    constructor(parent: ParentNodeDefinition, bind: NoteBindDefinition, bodyElement: InputDefinition, noteTextDefinition: NoteTextDefinition, node: Element);
+}

package/dist/parse/expression/RepeatCountControlExpression.d.ts

@@ -0,0 +1,19 @@
+import { RepeatElementDefinition } from '../../body/RepeatElementDefinition.ts';
+import { DependentExpression } from '../../expression/DependentExpression.ts';
+
+/**
+ * Represents either of these
+ * {@link https://getodk.github.io/xforms-spec/#body-attributes | body attributes}:
+ *
+ * - `jr:count`
+ * - `jr:noAddRemove`
+ *
+ * In both cases, the downstream effect is that the engine is responsible for
+ * controlling the count of a repeat range's instances. Representing both cases
+ * should simplify client usage, as well as implementation of the internal
+ * representation of {@link RepeatRangeControlledNode}.
+ */
+export declare class RepeatCountControlExpression extends DependentExpression<'number'> {
+    static from(bodyElement: RepeatElementDefinition, initialCount: number): RepeatCountControlExpression | null;
+    private constructor();
+}

package/dist/parse/text/HintDefinition.d.ts

@@ -0,0 +1,9 @@
+import { XFormDefinition } from '../../XFormDefinition.ts';
+import { AnyControlDefinition } from '../../body/control/ControlDefinition.ts';
+import { TextElementDefinition } from './abstract/TextElementDefinition.ts';
+
+export declare class HintDefinition extends TextElementDefinition<'hint'> {
+    static forElement(form: XFormDefinition, owner: AnyControlDefinition): HintDefinition | null;
+    readonly role = "hint";
+    private constructor();
+}

package/dist/parse/text/ItemLabelDefinition.d.ts

@@ -0,0 +1,9 @@
+import { XFormDefinition } from '../../XFormDefinition.ts';
+import { ItemDefinition } from '../../body/control/select/ItemDefinition.ts';
+import { TextElementDefinition } from './abstract/TextElementDefinition.ts';
+
+export declare class ItemLabelDefinition extends TextElementDefinition<'item-label'> {
+    static from(form: XFormDefinition, owner: ItemDefinition): ItemLabelDefinition | null;
+    readonly role = "item-label";
+    private constructor();
+}

package/dist/parse/text/ItemsetLabelDefinition.d.ts

@@ -0,0 +1,13 @@
+import { XFormDefinition } from '../../XFormDefinition.ts';
+import { ItemDefinition } from '../../body/control/select/ItemDefinition.ts';
+import { ItemsetDefinition } from '../../body/control/select/ItemsetDefinition.ts';
+import { RefAttributeChunk } from './abstract/TextElementDefinition.ts';
+import { TextRangeDefinition } from './abstract/TextRangeDefinition.ts';
+
+export type ItemLabelOwner = ItemDefinition | ItemsetDefinition;
+export declare class ItemsetLabelDefinition extends TextRangeDefinition<'item-label'> {
+    static from(form: XFormDefinition, owner: ItemsetDefinition): ItemsetLabelDefinition | null;
+    readonly role = "item-label";
+    readonly chunks: readonly [RefAttributeChunk];
+    private constructor();
+}

package/dist/parse/text/LabelDefinition.d.ts

@@ -0,0 +1,15 @@
+import { XFormDefinition } from '../../XFormDefinition.ts';
+import { AnyGroupElementDefinition } from '../../body/BodyDefinition.ts';
+import { RepeatElementDefinition } from '../../body/RepeatElementDefinition.ts';
+import { AnyControlDefinition } from '../../body/control/ControlDefinition.ts';
+import { BaseGroupDefinition } from '../../body/group/BaseGroupDefinition.ts';
+import { TextElementDefinition } from './abstract/TextElementDefinition.ts';
+
+export type LabelOwner = AnyControlDefinition | AnyGroupElementDefinition | RepeatElementDefinition;
+export declare class LabelDefinition extends TextElementDefinition<'label'> {
+    static forControl(form: XFormDefinition, control: AnyControlDefinition): LabelDefinition | null;
+    static forRepeatGroup(form: XFormDefinition, repeat: RepeatElementDefinition): LabelDefinition | null;
+    static forGroup(form: XFormDefinition, group: BaseGroupDefinition<any>): LabelDefinition | null;
+    readonly role = "label";
+    private constructor();
+}

package/dist/parse/text/MessageDefinition.d.ts

@@ -0,0 +1,15 @@
+import { BindDefinition } from '../../model/BindDefinition.ts';
+import { StaticTextChunkDefinition } from './StaticTextChunkDefinition.ts';
+import { TranslationChunkDefinition } from './TranslationChunkDefinition.ts';
+import { TextBindAttributeLocalName, TextSourceNode, TextRangeDefinition } from './abstract/TextRangeDefinition.ts';
+
+export type MessageSourceNode = TextSourceNode<TextBindAttributeLocalName>;
+type MessageChunk = StaticTextChunkDefinition | TranslationChunkDefinition;
+export declare class MessageDefinition<Type extends TextBindAttributeLocalName> extends TextRangeDefinition<Type> {
+    readonly role: Type;
+    static from<Type extends TextBindAttributeLocalName>(bind: BindDefinition, type: Type): MessageDefinition<Type> | null;
+    readonly chunks: readonly [MessageChunk];
+    private constructor();
+}
+export type AnyMessageDefinition = MessageDefinition<TextBindAttributeLocalName>;
+export {};

package/dist/parse/text/OutputChunkDefinition.d.ts

@@ -0,0 +1,8 @@
+import { TextChunkDefinition } from './abstract/TextChunkDefinition.ts';
+import { AnyTextRangeDefinition } from './abstract/TextRangeDefinition.ts';
+
+export declare class OutputChunkDefinition extends TextChunkDefinition<'output'> {
+    static from(context: AnyTextRangeDefinition, element: Element): OutputChunkDefinition | null;
+    readonly source = "output";
+    private constructor();
+}

package/dist/parse/text/ReferenceChunkDefinition.d.ts

@@ -0,0 +1,8 @@
+import { TextChunkDefinition } from './abstract/TextChunkDefinition.ts';
+import { AnyTextRangeDefinition } from './abstract/TextRangeDefinition.ts';
+
+export declare class ReferenceChunkDefinition extends TextChunkDefinition<'reference'> {
+    static from(context: AnyTextRangeDefinition, refExpression: string): ReferenceChunkDefinition;
+    readonly source = "reference";
+    private constructor();
+}

package/dist/parse/text/StaticTextChunkDefinition.d.ts

@@ -0,0 +1,10 @@
+import { TextChunkDefinition } from './abstract/TextChunkDefinition.ts';
+import { AnyTextRangeDefinition } from './abstract/TextRangeDefinition.ts';
+
+export type StaticTextChunkSourceNode = Attr | Text;
+export declare class StaticTextChunkDefinition extends TextChunkDefinition<'static'> {
+    readonly stringValue: string;
+    static from(context: AnyTextRangeDefinition, stringValue: string): StaticTextChunkDefinition;
+    readonly source = "static";
+    private constructor();
+}

package/dist/parse/text/TranslationChunkDefinition.d.ts

@@ -0,0 +1,9 @@
+import { TextChunkDefinition } from './abstract/TextChunkDefinition.ts';
+import { AnyTextRangeDefinition } from './abstract/TextRangeDefinition.ts';
+
+export declare class TranslationChunkDefinition extends TextChunkDefinition<'translation'> {
+    static fromMessage(context: AnyTextRangeDefinition, maybeExpression: string): TranslationChunkDefinition | null;
+    static from(context: AnyTextRangeDefinition, maybeExpression: string): TranslationChunkDefinition | null;
+    readonly source = "translation";
+    private constructor();
+}

package/dist/parse/text/abstract/TextChunkDefinition.d.ts

@@ -0,0 +1,18 @@
+import { TextChunkSource } from '../../../client/TextRange.ts';
+import { DependentExpression } from '../../../expression/DependentExpression.ts';
+import { OutputChunkDefinition } from '../OutputChunkDefinition.ts';
+import { ReferenceChunkDefinition } from '../ReferenceChunkDefinition.ts';
+import { StaticTextChunkDefinition } from '../StaticTextChunkDefinition.ts';
+import { TranslationChunkDefinition } from '../TranslationChunkDefinition.ts';
+import { AnyTextRangeDefinition } from './TextRangeDefinition.ts';
+
+interface TextChunkDefinitionOptions {
+    readonly isTranslated?: true;
+}
+export declare abstract class TextChunkDefinition<Source extends TextChunkSource> extends DependentExpression<'string'> {
+    abstract readonly source: Source;
+    readonly stringValue?: string;
+    constructor(context: AnyTextRangeDefinition, expression: string, options?: TextChunkDefinitionOptions);
+}
+export type AnyTextChunkDefinition = OutputChunkDefinition | ReferenceChunkDefinition | StaticTextChunkDefinition | TranslationChunkDefinition;
+export {};

package/dist/parse/text/abstract/TextElementDefinition.d.ts

@@ -0,0 +1,23 @@
+import { XFormDefinition } from '../../../XFormDefinition.ts';
+import { ItemDefinition } from '../../../body/control/select/ItemDefinition.ts';
+import { ElementTextRole } from '../../../client/TextRange.ts';
+import { HintDefinition } from '../HintDefinition.ts';
+import { ItemLabelDefinition } from '../ItemLabelDefinition.ts';
+import { ItemsetLabelDefinition } from '../ItemsetLabelDefinition.ts';
+import { LabelDefinition, LabelOwner } from '../LabelDefinition.ts';
+import { OutputChunkDefinition } from '../OutputChunkDefinition.ts';
+import { ReferenceChunkDefinition } from '../ReferenceChunkDefinition.ts';
+import { StaticTextChunkDefinition } from '../StaticTextChunkDefinition.ts';
+import { TranslationChunkDefinition } from '../TranslationChunkDefinition.ts';
+import { TextSourceNode, TextRangeDefinition } from './TextRangeDefinition.ts';
+
+export type RefAttributeChunk = ReferenceChunkDefinition | TranslationChunkDefinition;
+type TextElementChildChunk = OutputChunkDefinition | StaticTextChunkDefinition;
+type TextElementChunks = readonly [RefAttributeChunk] | readonly TextElementChildChunk[];
+type TextElementOwner = ItemDefinition | LabelOwner;
+export declare abstract class TextElementDefinition<Role extends ElementTextRole> extends TextRangeDefinition<Role> {
+    readonly chunks: TextElementChunks;
+    constructor(form: XFormDefinition, owner: TextElementOwner, sourceNode: TextSourceNode<Role>);
+}
+export type AnyTextElementDefinition = HintDefinition | ItemLabelDefinition | ItemsetLabelDefinition | LabelDefinition;
+export {};

package/dist/parse/text/abstract/TextRangeDefinition.d.ts

@@ -0,0 +1,35 @@
+import { LocalNamedElement } from '../../../../../common/types/dom.ts';
+import { XFormDefinition } from '../../../XFormDefinition.ts';
+import { TextRole } from '../../../client/TextRange.ts';
+import { DependencyContext } from '../../../expression/DependencyContext.ts';
+import { AnyDependentExpression } from '../../../expression/DependentExpression.ts';
+import { AnyMessageDefinition } from '../MessageDefinition.ts';
+import { AnyTextChunkDefinition } from './TextChunkDefinition.ts';
+import { AnyTextElementDefinition } from './TextElementDefinition.ts';
+
+export type TextBindAttributeLocalName = 'constraintMsg' | 'requiredMsg';
+export type TextBodyElementLocalName = 'hint' | 'label';
+interface TextSourceNodes {
+    readonly constraintMsg: null;
+    readonly hint: LocalNamedElement<'hint'>;
+    readonly label: LocalNamedElement<'label'>;
+    readonly 'item-label': LocalNamedElement<'label'>;
+    readonly requiredMsg: null;
+}
+export type TextSourceNode<Type extends TextRole> = TextSourceNodes[Type];
+export declare abstract class TextRangeDefinition<Role extends TextRole> extends DependencyContext {
+    readonly form: XFormDefinition;
+    readonly ownerContext: DependencyContext;
+    readonly sourceNode: TextSourceNode<Role>;
+    abstract readonly role: Role;
+    readonly parentReference: string | null;
+    readonly reference: string | null;
+    abstract readonly chunks: readonly AnyTextChunkDefinition[];
+    get isTranslated(): boolean;
+    set isTranslated(value: true);
+    protected constructor(form: XFormDefinition, ownerContext: DependencyContext, sourceNode: TextSourceNode<Role>);
+    registerDependentExpression(expression: AnyDependentExpression): void;
+    toJSON(): object;
+}
+export type AnyTextRangeDefinition = AnyMessageDefinition | AnyTextElementDefinition;
+export {};

package/dist/parse/xpath/dependency-analysis.d.ts

@@ -0,0 +1,40 @@
+export interface PathResolutionOptions {
+    /**
+     * Excludes direct references to the nodeset specified as a context. This flag
+     * has earlier precedent as `ignoreContextReference` in similar internal APIs.
+     * The intent, in part, is to allow for certain in-spec exceptions to cycle
+     * analysis (which we previously did explicitly, and foresee reintroducing in
+     * some form relatively soon). As such, the default for this flag should be
+     * overridden when a computation is (A) not among the core `<bind>`
+     * computations or (B) is a computation which is explicitly expected to have
+     * self-references (such as `constraint`).
+     *
+     * @default false
+     *
+     * @todo It is highly likely we will eliminate this in the future. We
+     * considered removing its precursor (and existing code now referencing this)
+     * in {@link https://github.com/getodk/web-forms/pull/67}, but ran into issues
+     * with some of the reactive logic introduced there. It's likely that
+     * subsequent improvements have addressed those issues, but it's also likely
+     * that we will want similar special casing when we reintroduce explicit graph
+     * cycle analysis.
+     */
+    readonly ignoreReferenceToContextPath?: boolean;
+}
+/**
+ * Resolves XPath paths referenced by an arbitrary expression to XForms
+ * `nodeset` references:
+ *
+ * 1. The provided {@link expression} is analyzed to find path sub-expressions
+ *    (LocationPaths, sub-expressions with a node-set producing FilterExpr).
+ *
+ * 2. When a {@link contextNodeset} is available, each sub-expression is
+ *    resolved to that context. See {@link resolvePath} for additional
+ *    detail.
+ *
+ * 3. Once resolved, each dependency path is further analyzed to identify
+ *    sub-expressions in any of its predicates, resolving each to their
+ *    respective predicates' Steps. See {@link resolvePredicateReference} for
+ *    additional detail.
+ */
+export declare const resolveDependencyNodesets: (contextNodeset: string | null, expression: string, options?: PathResolutionOptions) => readonly string[];

package/dist/parse/xpath/path-resolution.d.ts

@@ -0,0 +1,70 @@
+import { AbsoluteRootLocationPathNode, FilterExprNode, RelativeStepSyntaxLiteralNode, StepNode } from '@getodk/xpath/static/grammar/SyntaxNode.js';
+import { PathExpressionNode } from './semantic-analysis.ts';
+
+type AbsolutePathHead = 
+/** / - as first character in LocationPath */
+AbsoluteRootLocationPathNode
+/** // - as first characters in LocationPath */
+ | RelativeStepSyntaxLiteralNode;
+/**
+ * fn(...args) - as first (and potentially only) part of a path expression,
+ * where the function is either known to produce a node-set result, or where
+ * other aspects of the exression's syntax are inherently node-set producing.
+ */
+type FilterPathExprHead = FilterExprNode;
+type StepLikeNode = 
+/** // - shorthand for `/descendant-or-self::node()/`  */
+RelativeStepSyntaxLiteralNode
+/** Any _actual_ Step in a LocationPath */
+ | StepNode;
+type PathNodeListHead = AbsolutePathHead | FilterPathExprHead | StepLikeNode;
+/**
+ * A path node list is a semi-flattened representation of...
+ *
+ * - Any XPath LocationPath expression:
+ *   - AbsoluteLocationPath
+ *   - RelativeLocationPath
+ *
+ * - Any expression beginning with a FilterExpr which is known to produce a
+ *   node-set result
+ *
+ * The flattening of these syntax representations is used to perform various
+ * aspects of path resolution logic, accounting for complexities of XPath syntax
+ * and semantics in a roughly linear/list processing manner.
+ */
+export type PathNodeList<Head extends PathNodeListHead = PathNodeListHead> = readonly [
+    head: Head,
+    ...tail: StepLikeNode[]
+];
+export declare const resolvePath: (contextNode: PathExpressionNode | null, pathNode: PathExpressionNode) => PathNodeList;
+/**
+ * Resolves the parsed path {@link predicatePathNode}, in the context of:
+ *
+ * - The {@link contextNode} context, representing the original expression's
+ *   context (if one was available)
+ *
+ * - The {@link stepContextNodes} context, representing the cumulative portion
+ *   of the source path where {@link predicatePathNode} was parsed from a
+ *   Predicate sub-expression
+ *
+ * Both contexts are necessary for resolution to ensure that:
+ *
+ * - A `current()` call within the predicate's sub-expression is contextualized
+ *   to the current `nodeset` reference associated with the original expression
+ *
+ * - A `.` self-reference within the predicate's sub-expression is
+ *   contextualized to the Step in which it occurred
+ */
+export declare const resolvePredicateReference: (contextNode: PathExpressionNode | null, stepContextNodes: PathNodeList, predicatePathNode: PathExpressionNode) => PathNodeList;
+interface PathSerializationOptions {
+    /**
+     * @default false
+     */
+    readonly stripPredicates: boolean;
+}
+/**
+ * Serializes a resolved {@link PathNodeList} to its XPath expression
+ * representation, optionally stripping predicates.
+ */
+export declare const serializeNodesetReference: (nodes: PathNodeList, options: PathSerializationOptions) => string;
+export {};