@getodk/xforms-engine 0.1.1 → 0.3.0

package/dist/model/NodeDefinition.d.ts

@@ -1,12 +1,12 @@
 import { AnyBodyElementDefinition } from '../body/BodyDefinition.ts';
-import { RepeatDefinition } from '../body/RepeatDefinition.ts';
+import { RepeatElementDefinition } from '../body/RepeatElementDefinition.ts';
 import { BindDefinition } from './BindDefinition.ts';
+import { LeafNodeDefinition } from './LeafNodeDefinition.ts';
 import { RepeatInstanceDefinition } from './RepeatInstanceDefinition.ts';
-import { RepeatSequenceDefinition } from './RepeatSequenceDefinition.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.:
@@ -16,12 +16,12 @@ import { ValueNodeDefinition } from './ValueNodeDefinition.ts';
  */
 export type RootNodeType = 'root';
 /**
- * Corresponds to a sequence of model/entry DOM subtrees which in turn
+ * Corresponds to a range/sequence of model/entry DOM subtrees which in turn
  * corresponds to a <repeat> in the form body definition.
  */
-export type RepeatSequenceType = 'repeat-sequence';
+export type RepeatRangeType = 'repeat-range';
 /**
- * Corresponds to a template definition for a repeat sequence, which either has
+ * Corresponds to a template definition for a repeat range, which either has
  * an explicit `jr:template=""` attribute in the form definition or is inferred
  * as a template from the form's first element matched by a <repeat nodeset>.
  */
@@ -29,7 +29,7 @@ export type RepeatTemplateType = 'repeat-template';
 /**
  * Corresponds to a single instance of a model/entry DOM subtree which
  * in turn corresponds to a <repeat> in the form body definition, and a
- * 'repeat-sequence' definition.
+ * 'repeat-range' definition.
  */
 export type RepeatInstanceType = 'repeat-instance';
 /**
@@ -44,22 +44,22 @@ 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 | RepeatSequenceType | 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 = RepeatSequenceDefinition | 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-sequence' ? readonly RepeatInstanceDefinition[] : 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-sequence' ? null : Element;
-export type NodeDefaultValue<Type extends NodeDefinitionType> = Type extends 'value-node' ? string : null;
+export type ModelNode<Type extends NodeDefinitionType> = Type extends 'repeat-range' ? null : Element;
+export type NodeDefaultValue<Type extends NodeDefinitionType> = Type extends 'leaf-node' ? string : null;
 export interface NodeDefinition<Type extends NodeDefinitionType> {
     readonly type: Type;
     readonly bind: BindDefinition;
     readonly nodeset: string;
     readonly nodeName: string;
-    readonly bodyElement: AnyBodyElementDefinition | RepeatDefinition | null;
+    readonly bodyElement: AnyBodyElementDefinition | RepeatElementDefinition | null;
     readonly isTranslated: boolean;
     readonly dependencyExpressions: ReadonlySet<string>;
     readonly root: RootDefinition;
@@ -69,7 +69,7 @@ export interface NodeDefinition<Type extends NodeDefinitionType> {
     readonly node: ModelNode<Type>;
     readonly defaultValue: NodeDefaultValue<Type>;
 }
-export type AnyNodeDefinition = RootDefinition | RepeatSequenceDefinition | 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,16 +1,15 @@
-import { RepeatDefinition } from '../body/RepeatDefinition.ts';
+import { RepeatElementDefinition } from '../body/RepeatElementDefinition.ts';
 import { DescendentNodeDefinition } from './DescendentNodeDefinition.ts';
 import { ChildNodeDefinition, NodeDefinition } from './NodeDefinition.ts';
-import { RepeatSequenceDefinition } from './RepeatSequenceDefinition.ts';
+import { AnyRepeatRangeDefinition } from './RepeatRangeDefinition.ts';
 
-export declare class RepeatInstanceDefinition extends DescendentNodeDefinition<'repeat-instance', RepeatDefinition> implements NodeDefinition<'repeat-instance'> {
-    protected readonly sequence: RepeatSequenceDefinition;
+export declare class RepeatInstanceDefinition extends DescendentNodeDefinition<'repeat-instance', RepeatElementDefinition> implements NodeDefinition<'repeat-instance'> {
     readonly node: Element;
     readonly type = "repeat-instance";
     readonly nodeName: string;
     readonly children: readonly ChildNodeDefinition[];
     readonly instances: null;
     readonly defaultValue: null;
-    constructor(sequence: RepeatSequenceDefinition, node: Element);
-    toJSON(): Omit<this, "toJSON" | "parent" | "bind" | "root" | "bodyElement" | "sequence">;
+    constructor(range: AnyRepeatRangeDefinition, node: Element);
+    toJSON(): Omit<this, "toJSON" | "parent" | "bind" | "root" | "bodyElement">;
 }

package/dist/model/RepeatRangeDefinition.d.ts

@@ -0,0 +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 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;
+    private constructor();
+    isControlled(): this is ControlledRepeatRangeDefinition;
+    isUncontrolled(): this is UncontrolledRepeatRangeDefinition;
+    toJSON(): Omit<this, "toJSON" | "parent" | "bind" | "root" | "bodyElement" | "isControlled" | "isUncontrolled">;
+}

package/dist/model/RepeatTemplateDefinition.d.ts

@@ -1,8 +1,8 @@
 import { JAVAROSA_NAMESPACE_URI } from '../../../common/src/constants/xmlns.ts';
-import { RepeatDefinition } from '../body/RepeatDefinition.ts';
+import { RepeatElementDefinition } from '../body/RepeatElementDefinition.ts';
 import { DescendentNodeDefinition } from './DescendentNodeDefinition.ts';
 import { ChildNodeDefinition, NodeDefinition } from './NodeDefinition.ts';
-import { RepeatSequenceDefinition } from './RepeatSequenceDefinition.ts';
+import { RepeatRangeDefinition } from './RepeatRangeDefinition.ts';
 
 interface ExplicitRepeatTemplateElement extends Element {
     getAttributeNS(namespaceURI: typeof JAVAROSA_NAMESPACE_URI, name: 'template'): string;
@@ -14,17 +14,16 @@ interface ParsedRepeatNodes {
     readonly template: RepeatTemplateDefinition;
     readonly instanceNodes: readonly Element[];
 }
-export declare class RepeatTemplateDefinition extends DescendentNodeDefinition<'repeat-template', RepeatDefinition> implements NodeDefinition<'repeat-template'> {
-    protected readonly sequence: RepeatSequenceDefinition;
+export declare class RepeatTemplateDefinition extends DescendentNodeDefinition<'repeat-template', RepeatElementDefinition> implements NodeDefinition<'repeat-template'> {
     protected readonly templateNode: ExplicitRepeatTemplateElement;
-    static parseModelNodes(sequence: RepeatSequenceDefinition, modelNodes: readonly [Element, ...Element[]]): ParsedRepeatNodes;
+    static parseModelNodes(range: RepeatRangeDefinition, modelNodes: readonly [Element, ...Element[]]): ParsedRepeatNodes;
     readonly type = "repeat-template";
     readonly node: Element;
     readonly nodeName: string;
     readonly children: readonly ChildNodeDefinition[];
     readonly instances: null;
     readonly defaultValue: null;
-    protected constructor(sequence: RepeatSequenceDefinition, templateNode: ExplicitRepeatTemplateElement);
-    toJSON(): Omit<this, "toJSON" | "parent" | "bind" | "root" | "bodyElement" | "sequence">;
+    protected constructor(range: RepeatRangeDefinition, templateNode: ExplicitRepeatTemplateElement);
+    toJSON(): Omit<this, "toJSON" | "parent" | "bind" | "root" | "bodyElement">;
 }
 export {};

package/dist/model/RootDefinition.d.ts

@@ -1,4 +1,5 @@
 import { XFormDefinition } from '../XFormDefinition.ts';
+import { BodyClassList } from '../body/BodyDefinition.ts';
 import { BindDefinition } from './BindDefinition.ts';
 import { ModelDefinition } from './ModelDefinition.ts';
 import { ChildNodeDefinition, NodeDefinition, ParentNodeDefinition } from './NodeDefinition.ts';
@@ -6,6 +7,7 @@ import { ChildNodeDefinition, NodeDefinition, ParentNodeDefinition } from './Nod
 export declare class RootDefinition implements NodeDefinition<'root'> {
     protected readonly form: XFormDefinition;
     protected readonly model: ModelDefinition;
+    readonly classes: BodyClassList;
     readonly type = "root";
     readonly bind: BindDefinition;
     readonly nodeset: string;
@@ -19,7 +21,7 @@ export declare class RootDefinition implements NodeDefinition<'root'> {
     readonly defaultValue: null;
     readonly isTranslated = false;
     readonly dependencyExpressions: ReadonlySet<string>;
-    constructor(form: XFormDefinition, model: ModelDefinition);
+    constructor(form: XFormDefinition, model: ModelDefinition, classes: BodyClassList);
     buildSubtree(parent: ParentNodeDefinition): readonly ChildNodeDefinition[];
     toJSON(): Omit<this, "model" | "toJSON" | "form" | "bind" | "root" | "bodyElement" | "buildSubtree">;
 }

package/dist/model/SubtreeDefinition.d.ts

@@ -1,9 +1,9 @@
-import { AnyBodyElementDefinition, NonRepeatGroupElementDefinition } from '../body/BodyDefinition.ts';
+import { AnyBodyElementDefinition, AnyGroupElementDefinition } from '../body/BodyDefinition.ts';
 import { BindDefinition } from './BindDefinition.ts';
 import { DescendentNodeDefinition } from './DescendentNodeDefinition.ts';
 import { ChildNodeDefinition, NodeDefinition, ParentNodeDefinition } from './NodeDefinition.ts';
 
-export declare class SubtreeDefinition extends DescendentNodeDefinition<'subtree', NonRepeatGroupElementDefinition | null> implements NodeDefinition<'subtree'> {
+export declare class SubtreeDefinition extends DescendentNodeDefinition<'subtree', AnyGroupElementDefinition | null> implements NodeDefinition<'subtree'> {
     readonly node: Element;
     readonly type = "subtree";
     readonly nodeName: string;

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 {};

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

@@ -0,0 +1,30 @@
+import { PathNodeList } from './path-resolution.ts';
+import { PathExpressionNode } from './semantic-analysis.ts';
+
+/**
+ * Represents a pair of:
+ *
+ * - Path expression syntax referenced within a particular predicate, on any
+ *   Step within a source LocationPath and/or FilterExpr path. This
+ *   sub-expression is resolved as a member of the dependencies which may be
+ *   referenced by any arbitrary form expression.
+ *
+ * - The cumulative set of path nodes, from the start of the source path
+ *   expression, to the Step and Predicate where the sub-expression reference
+ *   was identified. This representation is used as **part** of the context used
+ *   to resolve the identified Predicate sub-expression for downstream
+ *   dependency subscriptions. (Each predicate sub-expression is **further
+ *   contextualized** by the original context in which the source path is
+ *   defined.)
+ */
+export interface PredicateReference {
+    readonly predicatePathNode: PathExpressionNode;
+    readonly stepContextNodes: PathNodeList;
+}
+/**
+ * Identifies path sub-expressions within any of a path's Predicates, along with
+ * the step context in which they are found.
+ *
+ * @see {@link PredicateReference} for details on the produced structures.
+ */
+export declare const findPredicateReferences: (pathNodes: PathNodeList) => readonly PredicateReference[];

package/dist/parse/xpath/reference-parsing.d.ts

@@ -0,0 +1,18 @@
+import { PartiallyKnownString } from '../../../../common/types/string/PartiallyKnownString.ts';
+
+interface ReferenceParsingContext {
+    readonly reference: string | null;
+    readonly parent?: ReferenceParsingContext | null;
+}
+type ReferenceAttributeName = PartiallyKnownString<'nodeset' | 'ref'>;
+interface KnownAttributeElement<AttributeName extends string> extends Element {
+    getAttribute(name: AttributeName): string;
+    getAttribute(name: string): string | null;
+}
+type ParsedReferenceAttribute<T extends Element, AttributeName extends string> = T extends KnownAttributeElement<AttributeName> ? string : string | null;
+/**
+ * Parses a `nodeset` reference from an arbitrary form definition element, and
+ * resolves that (potentially relative) reference to the provided context.
+ */
+export declare const parseNodesetReference: <const AttributeName extends ReferenceAttributeName, T extends Element | KnownAttributeElement<AttributeName>>(parentContext: ReferenceParsingContext, element: T, attributeName: AttributeName) => ParsedReferenceAttribute<T, AttributeName>;
+export {};