@getodk/xforms-engine 0.2.0 → 0.4.0

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

@@ -2,14 +2,13 @@ import { AnyBodyElementDefinition, ControlElementDefinition } from '../body/Body
 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;
     readonly defaultValue: string;
     constructor(parent: ParentNodeDefinition, bind: BindDefinition, bodyElement: AnyBodyElementDefinition | null, node: Element);
-    toJSON(): Omit<this, "toJSON" | "parent" | "bind" | "root" | "bodyElement">;
+    toJSON(): Omit<this, "parent" | "toJSON" | "bind" | "root" | "bodyElement">;
 }

package/dist/{model → parse/model}/ModelBindMap.d.ts

@@ -2,7 +2,6 @@ import { XFormDefinition } from '../XFormDefinition.ts';
 import { BindDefinition } from './BindDefinition.ts';
 import { BindNodeset } from './BindElement.ts';
 import { ModelDefinition } from './ModelDefinition.ts';
-
 type TopologicalSortIndex = number;
 export type SortedNodesetIndexes = ReadonlyMap<BindNodeset, TopologicalSortIndex>;
 export declare class ModelBindMap extends Map<BindNodeset, BindDefinition> {

package/dist/{model → parse/model}/ModelDefinition.d.ts

@@ -1,11 +1,10 @@
 import { XFormDefinition } from '../XFormDefinition.ts';
 import { ModelBindMap } from './ModelBindMap.ts';
 import { RootDefinition } from './RootDefinition.ts';
-
 export declare class ModelDefinition {
     readonly form: XFormDefinition;
     readonly binds: ModelBindMap;
     readonly root: RootDefinition;
     constructor(form: XFormDefinition);
-    toJSON(): Omit<this, "toJSON" | "form">;
+    toJSON(): Omit<this, "form" | "toJSON">;
 }

package/dist/{model → parse/model}/NodeDefinition.d.ts

@@ -1,13 +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 +43,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 +68,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/parse/model/NoteNodeDefinition.d.ts

@@ -0,0 +1,30 @@
+import { AnyBodyElementDefinition } from '../body/BodyDefinition.ts';
+import { InputDefinition } from '../body/control/InputDefinition.ts';
+import { BindComputationExpression } from '../expression/BindComputationExpression.ts';
+import { ConstantTruthyDependentExpression } from '../expression/abstract/DependentExpression.ts';
+import { HintDefinition } from '../text/HintDefinition.ts';
+import { LabelDefinition } from '../text/LabelDefinition.ts';
+import { BindDefinition } from './BindDefinition.ts';
+import { LeafNodeDefinition } from './LeafNodeDefinition.ts';
+import { ParentNodeDefinition } from './NodeDefinition.ts';
+export type NoteReadonlyDefinition = BindComputationExpression<'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/{model → parse/model}/RepeatInstanceDefinition.d.ts

@@ -1,8 +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;
     readonly type = "repeat-instance";
@@ -10,6 +9,6 @@ export declare class RepeatInstanceDefinition extends DescendentNodeDefinition<'
     readonly children: readonly ChildNodeDefinition[];
     readonly instances: null;
     readonly defaultValue: null;
-    constructor(range: RepeatRangeDefinition, node: Element);
-    toJSON(): Omit<this, "toJSON" | "parent" | "bind" | "root" | "bodyElement">;
+    constructor(range: AnyRepeatRangeDefinition, node: Element);
+    toJSON(): Omit<this, "parent" | "toJSON" | "bind" | "root" | "bodyElement">;
 }

package/dist/{model → parse/model}/RepeatRangeDefinition.d.ts

@@ -1,20 +1,29 @@
 import { RepeatElementDefinition } from '../body/RepeatElementDefinition.ts';
+import { RepeatCountControlExpression } from '../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, "parent" | "toJSON" | "bind" | "root" | "bodyElement" | "isControlled" | "isUncontrolled">;
 }

package/dist/{model → parse/model}/RepeatTemplateDefinition.d.ts

@@ -1,9 +1,8 @@
-import { JAVAROSA_NAMESPACE_URI } from '../../../common/src/constants/xmlns.ts';
+import { JAVAROSA_NAMESPACE_URI } from '../../../../common/src/constants/xmlns.ts';
 import { RepeatElementDefinition } from '../body/RepeatElementDefinition.ts';
 import { DescendentNodeDefinition } from './DescendentNodeDefinition.ts';
 import { ChildNodeDefinition, NodeDefinition } from './NodeDefinition.ts';
 import { RepeatRangeDefinition } from './RepeatRangeDefinition.ts';
-
 interface ExplicitRepeatTemplateElement extends Element {
     getAttributeNS(namespaceURI: typeof JAVAROSA_NAMESPACE_URI, name: 'template'): string;
     getAttributeNS(namespaceURI: string | null, name: string): string | null;
@@ -24,6 +23,6 @@ export declare class RepeatTemplateDefinition extends DescendentNodeDefinition<'
     readonly instances: null;
     readonly defaultValue: null;
     protected constructor(range: RepeatRangeDefinition, templateNode: ExplicitRepeatTemplateElement);
-    toJSON(): Omit<this, "toJSON" | "parent" | "bind" | "root" | "bodyElement">;
+    toJSON(): Omit<this, "parent" | "toJSON" | "bind" | "root" | "bodyElement">;
 }
 export {};

package/dist/{model → parse/model}/RootDefinition.d.ts

@@ -1,9 +1,8 @@
-import { XFormDefinition } from '../XFormDefinition.ts';
 import { BodyClassList } from '../body/BodyDefinition.ts';
+import { XFormDefinition } from '../XFormDefinition.ts';
 import { BindDefinition } from './BindDefinition.ts';
 import { ModelDefinition } from './ModelDefinition.ts';
 import { ChildNodeDefinition, NodeDefinition, ParentNodeDefinition } from './NodeDefinition.ts';
-
 export declare class RootDefinition implements NodeDefinition<'root'> {
     protected readonly form: XFormDefinition;
     protected readonly model: ModelDefinition;
@@ -23,5 +22,5 @@ export declare class RootDefinition implements NodeDefinition<'root'> {
     readonly dependencyExpressions: ReadonlySet<string>;
     constructor(form: XFormDefinition, model: ModelDefinition, classes: BodyClassList);
     buildSubtree(parent: ParentNodeDefinition): readonly ChildNodeDefinition[];
-    toJSON(): Omit<this, "model" | "toJSON" | "form" | "bind" | "root" | "bodyElement" | "buildSubtree">;
+    toJSON(): Omit<this, "form" | "toJSON" | "bind" | "model" | "root" | "bodyElement" | "buildSubtree">;
 }

package/dist/{model → parse/model}/SubtreeDefinition.d.ts

@@ -2,7 +2,6 @@ import { AnyBodyElementDefinition, AnyGroupElementDefinition } from '../body/Bod
 import { BindDefinition } from './BindDefinition.ts';
 import { DescendentNodeDefinition } from './DescendentNodeDefinition.ts';
 import { ChildNodeDefinition, NodeDefinition, ParentNodeDefinition } from './NodeDefinition.ts';
-
 export declare class SubtreeDefinition extends DescendentNodeDefinition<'subtree', AnyGroupElementDefinition | null> implements NodeDefinition<'subtree'> {
     readonly node: Element;
     readonly type = "subtree";
@@ -11,5 +10,5 @@ export declare class SubtreeDefinition extends DescendentNodeDefinition<'subtree
     readonly instances: null;
     readonly defaultValue: null;
     constructor(parent: ParentNodeDefinition, bind: BindDefinition, bodyElement: AnyBodyElementDefinition | null, node: Element);
-    toJSON(): Omit<this, "toJSON" | "parent" | "bind" | "root" | "bodyElement">;
+    toJSON(): Omit<this, "parent" | "toJSON" | "bind" | "root" | "bodyElement">;
 }

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

@@ -0,0 +1,8 @@
+import { XFormDefinition } from '../../parse/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,8 @@
+import { XFormDefinition } from '../../parse/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,12 @@
+import { XFormDefinition } from '../../parse/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,14 @@
+import { XFormDefinition } from '../../parse/XFormDefinition.ts';
+import { AnyGroupElementDefinition } from '../../parse/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,14 @@
+import { TextLiteralExpression } from '../expression/TextLiteralExpression.ts';
+import { TextTranslationExpression } from '../expression/TextTranslationExpression.ts';
+import { BindDefinition } from '../model/BindDefinition.ts';
+import { TextBindAttributeLocalName, TextSourceNode, TextRangeDefinition } from './abstract/TextRangeDefinition.ts';
+export type MessageSourceNode = TextSourceNode<TextBindAttributeLocalName>;
+type MessageChunk = TextLiteralExpression | TextTranslationExpression;
+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/abstract/TextElementDefinition.d.ts

@@ -0,0 +1,22 @@
+import { ElementTextRole } from '../../../client/TextRange.ts';
+import { XFormDefinition } from '../../../parse/XFormDefinition.ts';
+import { ItemDefinition } from '../../body/control/select/ItemDefinition.ts';
+import { TextLiteralExpression } from '../../expression/TextLiteralExpression.ts';
+import { TextOutputExpression } from '../../expression/TextOutputExpression.ts';
+import { TextReferenceExpression } from '../../expression/TextReferenceExpression.ts';
+import { TextTranslationExpression } from '../../expression/TextTranslationExpression.ts';
+import { HintDefinition } from '../HintDefinition.ts';
+import { ItemLabelDefinition } from '../ItemLabelDefinition.ts';
+import { ItemsetLabelDefinition } from '../ItemsetLabelDefinition.ts';
+import { LabelDefinition, LabelOwner } from '../LabelDefinition.ts';
+import { TextSourceNode, TextRangeDefinition } from './TextRangeDefinition.ts';
+export type RefAttributeChunk = TextReferenceExpression | TextTranslationExpression;
+type TextElementChildChunk = TextOutputExpression | TextLiteralExpression;
+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,34 @@
+import { LocalNamedElement } from '../../../../../common/types/dom.ts';
+import { TextRole } from '../../../client/TextRange.ts';
+import { XFormDefinition } from '../../../parse/XFormDefinition.ts';
+import { DependencyContext } from '../../expression/abstract/DependencyContext.ts';
+import { AnyDependentExpression } from '../../expression/abstract/DependentExpression.ts';
+import { AnyTextChunkExpression } from '../../expression/abstract/TextChunkExpression.ts';
+import { AnyMessageDefinition } from '../MessageDefinition.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 AnyTextChunkExpression[];
+    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,69 @@
+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,29 @@
+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,17 @@
+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 {};

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

@@ -0,0 +1,97 @@
+import { AbsoluteLocationPathNode, AnySyntaxNode, FilterPathExprNode, RelativeLocationPathNode } from '@getodk/xpath/static/grammar/SyntaxNode.js';
+type LocalNameLiteral<LocalName extends string> = LocalName | `${string}:${LocalName}`;
+type LocalNamedFunctionCallLiteral<LocalName extends string> = `${LocalNameLiteral<LocalName>}(${string})`;
+export type TranslationExpression = LocalNamedFunctionCallLiteral<'itext'>;
+/**
+ * Determines if an arbitrary XPath expression is (in whole) a translation
+ * expression (i.e. a call to `jr:itext`).
+ *
+ * @todo We may also want a companion function: `hasTranslationExpression`,
+ * which could be used for `<label ref>`/`<hint ref>` or anywhere else that an
+ * arbitrary expression may call `jr:itext`.
+ */
+export declare const isTranslationExpression: (expression: string) => expression is TranslationExpression;
+/**
+ * Predicate to determine if a FilterPathExpr (as currently produced by
+ * `tree-sitter-xpath`) is one of:
+ *
+ * - `current()`
+ * - `current()/...` (where `...` represents additional steps)
+ * - `current()//...` (^)
+ *
+ * @todo XPath grammar technically also allows for FilterExpr[Predicate],
+ * and our `tree-sitter-xpath` grammar/parser also allow for this. But
+ * `@getodk/xpath` types do not currently acknowledge this possibility.
+ */
+export declare const isCurrentPath: (syntaxNode: FilterPathExprNode) => boolean;
+declare const FILTER_PATH_NODE: unique symbol;
+/**
+ * Used to narrow types where a SyntaxNode with type 'filter_path_expr' is not
+ * **known to produce** a node-set result.
+ *
+ * This addresses some awkwardness in the XPath grammar (and our implementation
+ * parsing it) where FilterExpr _may be_ a FunctionCall, and one of the
+ * following _may also be true_:
+ *
+ * - The function call is known by name to produce a node-set result, **OR**
+ *
+ * - The function call is followed by one or more Steps (or the Step-like '//'
+ *   shorthand), which must produce a node-set **OR**
+ *
+ * - The function call is followed by one or more Predicates, which must produce
+ *   a node-set
+ *
+ * Any other FilterExpr (and thus our containing synthetic 'filter_path_expr'
+ * SyntaxNode) is treated as a non-path [sub-]expression, excluding it from
+ * analysis as such (and any downstream logic such as nodeset resolution).
+ */
+export interface FilterPathNode extends FilterPathExprNode {
+    readonly [FILTER_PATH_NODE]: true;
+}
+/**
+ * Determines whether a given expression beginning with a FilterExpr is known to
+ * produce a node-set result. Used in downstream dependency analysis, as well as
+ * path resolution.
+ */
+export declare const isNodeSetFilterPathExpression: (syntaxNode: FilterPathExprNode) => syntaxNode is FilterPathNode;
+export type PathExpressionNode = AbsoluteLocationPathNode | FilterPathNode | RelativeLocationPathNode;
+/**
+ * Locates sub-expression {@link PathExpressionNode}s within a parsed XPath
+ * expression (or any arbitrary sub-expression thereof).
+ */
+export declare const findLocationPathSubExpressionNodes: (syntaxNode: AnySyntaxNode) => readonly PathExpressionNode[];
+/**
+ * Gets the parsed representation of an XPath path expression, iff the complete
+ * expression is any {@link PathExpressionNode} syntax type.
+ */
+export declare const getPathExpressionNode: (expression: string) => PathExpressionNode | null;
+type BrandedExpression<Expression extends string, Brand extends symbol> = Expression & {
+    readonly [K in Brand]: true;
+};
+declare const CONSTANT_EXPRESSION: unique symbol;
+type CONSTANT_EXPRESSION = typeof CONSTANT_EXPRESSION;
+/**
+ * Represents an expression which produces a constant result:
+ *
+ * - Makes no reference to explicit dependencies
+ * - Does not depend on any known, implicit state
+ * - Evaluation does not depend in any way on context
+ * - Evaluation can be treated as referentially transparent
+ */
+export type ConstantExpression = BrandedExpression<string, CONSTANT_EXPRESSION>;
+/**
+ * @see {@link ConstantExpression}
+ */
+export declare const isConstantExpression: (expression: string) => expression is ConstantExpression;
+declare const CONSTANT_TRUTHY_EXPRESSION: unique symbol;
+type CONSTANT_TRUTHY_EXPRESSION = typeof CONSTANT_TRUTHY_EXPRESSION;
+/**
+ * Represents an expression which is {@link ConstantExpression | constant},
+ * and which will always produce `true` when evaluated as a boolean.
+ */
+export type ConstantTruthyExpression = BrandedExpression<ConstantExpression, CONSTANT_TRUTHY_EXPRESSION>;
+/**
+ * @see {@link ConstantTruthyExpression}
+ */
+export declare const isConstantTruthyExpression: (expression: string) => expression is ConstantTruthyExpression;
+export {};