@getodk/xforms-engine 0.5.0 → 0.7.0

package/dist/parse/model/DescendentNodeDefinition.d.ts

@@ -1,23 +1,14 @@
 import { AnyBodyElementDefinition } from '../body/BodyDefinition.ts';
 import { BindDefinition } from './BindDefinition.ts';
-import { ModelNode, NodeChildren, NodeDefaultValue, NodeDefinition, NodeDefinitionType, NodeInstances, NodeParent } from './NodeDefinition.ts';
+import { NodeDefinitionType, ParentNodeDefinition, NodeDefinition } from './NodeDefinition.ts';
 import { RootDefinition } from './RootDefinition.ts';
 export type DescendentNodeType = Exclude<NodeDefinitionType, 'root'>;
 type DescendentNodeBodyElement = AnyBodyElementDefinition;
-export declare abstract class DescendentNodeDefinition<Type extends DescendentNodeType, BodyElement extends DescendentNodeBodyElement | null = DescendentNodeBodyElement | null> implements NodeDefinition<Type> {
-    readonly parent: NodeParent<Type>;
-    readonly bind: BindDefinition;
+export declare abstract class DescendentNodeDefinition<Type extends DescendentNodeType, BodyElement extends DescendentNodeBodyElement | null = DescendentNodeBodyElement | null> extends NodeDefinition<Type> {
+    readonly parent: ParentNodeDefinition;
     readonly bodyElement: BodyElement;
-    abstract readonly type: Type;
-    abstract readonly children: NodeChildren<Type>;
-    abstract readonly instances: NodeInstances<Type>;
-    abstract readonly defaultValue: NodeDefaultValue<Type>;
-    abstract readonly node: ModelNode<Type>;
-    abstract readonly nodeName: string;
     readonly root: RootDefinition;
-    readonly nodeset: string;
     readonly isTranslated: boolean;
-    constructor(parent: NodeParent<Type>, bind: BindDefinition, bodyElement: BodyElement);
+    constructor(parent: ParentNodeDefinition, bind: BindDefinition, bodyElement: BodyElement);
 }
-export type AnyDescendantNodeDefinition = DescendentNodeDefinition<any, any>;
 export {};

package/dist/parse/model/ItextTranslationsDefinition.d.ts

@@ -0,0 +1,18 @@
+import { XFORMS_KNOWN_ATTRIBUTE, XFORMS_LOCAL_NAME, XFormsItextTranslationMap } from '@getodk/xpath';
+import { StaticDocument } from '../../integration/xpath/static-dom/StaticDocument.ts';
+import { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
+import { XFormDOM } from '../XFormDOM.ts';
+export interface ItextTranslationDefinition extends StaticDocument {
+    readonly rootDocument: ItextTranslationDefinition;
+    readonly root: ItextTranslationRootDefinition;
+}
+export interface ItextTranslationRootDefinition extends StaticElement {
+    readonly [XFORMS_LOCAL_NAME]: 'translation';
+    readonly [XFORMS_KNOWN_ATTRIBUTE]: 'lang';
+    readonly root: ItextTranslationRootDefinition;
+    readonly rootDocument: ItextTranslationDefinition;
+}
+export declare class ItextTranslationsDefinition extends Map<string, ItextTranslationRootDefinition> implements XFormsItextTranslationMap<ItextTranslationRootDefinition> {
+    static from(xformDOM: XFormDOM): ItextTranslationsDefinition;
+    private constructor();
+}

package/dist/parse/model/LeafNodeDefinition.d.ts

@@ -1,16 +1,18 @@
 import { ValueType } from '../../client/ValueType.ts';
+import { StaticLeafElement } from '../../integration/xpath/static-dom/StaticElement.ts';
+import { NamespaceDeclarationMap, NamedSubtreeDefinition } from '../../lib/names/NamespaceDeclarationMap.ts';
+import { QualifiedName } from '../../lib/names/QualifiedName.ts';
 import { AnyBodyElementDefinition, ControlElementDefinition } from '../body/BodyDefinition.ts';
 import { BindDefinition } from './BindDefinition.ts';
 import { DescendentNodeDefinition } from './DescendentNodeDefinition.ts';
-import { NodeDefinition, ParentNodeDefinition } from './NodeDefinition.ts';
-export declare class LeafNodeDefinition<V extends ValueType = ValueType> extends DescendentNodeDefinition<'leaf-node', ControlElementDefinition | null> implements NodeDefinition<'leaf-node'> {
-    readonly node: Element;
+import { ParentNodeDefinition } from './NodeDefinition.ts';
+export declare class LeafNodeDefinition<V extends ValueType = ValueType> extends DescendentNodeDefinition<'leaf-node', ControlElementDefinition | null> implements NamedSubtreeDefinition {
+    readonly template: StaticLeafElement;
     readonly type = "leaf-node";
     readonly valueType: V;
-    readonly nodeName: string;
+    readonly namespaceDeclarations: NamespaceDeclarationMap;
+    readonly qualifiedName: QualifiedName;
     readonly children: null;
-    readonly instances: null;
-    readonly defaultValue: string;
-    constructor(parent: ParentNodeDefinition, bind: BindDefinition, bodyElement: AnyBodyElementDefinition | null, node: Element);
+    constructor(parent: ParentNodeDefinition, bind: BindDefinition, bodyElement: AnyBodyElementDefinition | null, template: StaticLeafElement);
     toJSON(): Omit<this, "parent" | "toJSON" | "bind" | "root" | "bodyElement">;
 }

package/dist/parse/model/ModelDefinition.d.ts

@@ -1,12 +1,19 @@
+import { StaticDocument } from '../../integration/xpath/static-dom/StaticDocument.ts';
 import { XFormDefinition } from '../XFormDefinition.ts';
-import { ItextTranslationsDefinition } from './ItextTranslation/ItextTranslationsDefinition.ts';
+import { ItextTranslationsDefinition } from './ItextTranslationsDefinition.ts';
 import { ModelBindMap } from './ModelBindMap.ts';
+import { AnyNodeDefinition } from './NodeDefinition.ts';
+import { NodeDefinitionMap } from './nodeDefinitionMap.ts';
 import { RootDefinition } from './RootDefinition.ts';
 export declare class ModelDefinition {
     readonly form: XFormDefinition;
     readonly binds: ModelBindMap;
     readonly root: RootDefinition;
+    readonly nodes: NodeDefinitionMap;
+    readonly instance: StaticDocument;
     readonly itextTranslations: ItextTranslationsDefinition;
     constructor(form: XFormDefinition);
-    toJSON(): Omit<this, "form" | "toJSON">;
+    getNodeDefinition(nodeset: string): AnyNodeDefinition;
+    getRootDefinition(instance: StaticDocument): RootDefinition;
+    toJSON(): Omit<this, "form" | "toJSON" | "getNodeDefinition" | "getRootDefinition">;
 }

package/dist/parse/model/NodeDefinition.d.ts

@@ -1,73 +1,58 @@
+import { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
+import { NamedSubtreeDefinition, NamespaceDeclarationMap } from '../../lib/names/NamespaceDeclarationMap.ts';
+import { QualifiedName } from '../../lib/names/QualifiedName.ts';
 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 { AnyRepeatRangeDefinition } from './RepeatRangeDefinition.ts';
-import { RepeatTemplateDefinition } from './RepeatTemplateDefinition.ts';
+import { AnyRepeatDefinition } from './RepeatDefinition.ts';
 import { RootDefinition } from './RootDefinition.ts';
 import { SubtreeDefinition } from './SubtreeDefinition.ts';
 /**
- * Corresponds to the model/entry DOM root node, i.e.:
+ * Corresponds to a model instance root node, i.e.:
  *
  * - the element matching `/*` in primary instance expressions, a.k.a.
  * - `/h:html/h:head/xf:model/xf:instance[1]/*`
  */
 export type RootNodeType = 'root';
 /**
- * Corresponds to a range/sequence of model/entry DOM subtrees which in turn
- * corresponds to a <repeat> in the form body definition.
- */
-export type RepeatRangeType = 'repeat-range';
-/**
- * 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>.
- */
-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-range' definition.
+ * Corresponds to the combined concepts defining a "repeat".
+ *
+ * @see {@link RepeatDefinition} for details on these concepts and how they are used to produce a "repeat definition", as such.
+ *
+ * , including or
+ * referencing all of the following:
+ *
  */
-export type RepeatInstanceType = 'repeat-instance';
+export type RepeatType = 'repeat';
 /**
- * Corresponds to a model/entry DOM subtree which **does not** correspond to a
+ * Corresponds to a model instance subtree which **does not** correspond to a
  * <repeat> in the form definition. This will typically correspond to a <group>,
  * but this is not strictly necessary per spec (hence the distinct name).
  */
 export type SubtreeNodeType = 'subtree';
 /**
- * Corresponds to a model/entry DOM leaf node, i.e. one of:
+ * Corresponds to a model instance leaf node, i.e. one of:
  *
  * - An element with no child elements
  * - Any attribute corresponding to a bind's `nodeset` expression
  */
 export type LeafNodeType = 'leaf-node';
-export type NodeDefinitionType = RootNodeType | RepeatRangeType | RepeatTemplateType | RepeatInstanceType | SubtreeNodeType | LeafNodeType;
-export type ParentNodeDefinition = RootDefinition | RepeatTemplateDefinition | RepeatInstanceDefinition | SubtreeDefinition;
-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 'leaf-node' ? string : null;
-export interface NodeDefinition<Type extends NodeDefinitionType> {
-    readonly type: Type;
+export type NodeDefinitionType = RootNodeType | RepeatType | SubtreeNodeType | LeafNodeType;
+export type ParentNodeDefinition = RootDefinition | AnyRepeatDefinition | SubtreeDefinition;
+export type ChildNodeDefinition = AnyRepeatDefinition | LeafNodeDefinition | SubtreeDefinition;
+export declare abstract class NodeDefinition<Type extends NodeDefinitionType> implements NamedSubtreeDefinition {
     readonly bind: BindDefinition;
+    abstract readonly type: Type;
+    abstract readonly namespaceDeclarations: NamespaceDeclarationMap;
+    abstract readonly qualifiedName: QualifiedName;
+    abstract readonly bodyElement: AnyBodyElementDefinition | RepeatElementDefinition | null;
+    abstract readonly isTranslated: boolean;
+    abstract readonly root: RootDefinition;
+    abstract readonly parent: ParentNodeDefinition | null;
+    abstract readonly template: StaticElement;
+    abstract readonly children: readonly ChildNodeDefinition[] | null;
     readonly nodeset: string;
-    readonly nodeName: string;
-    readonly bodyElement: AnyBodyElementDefinition | RepeatElementDefinition | null;
-    readonly isTranslated: boolean;
-    readonly root: RootDefinition;
-    readonly parent: NodeParent<Type>;
-    readonly children: NodeChildren<Type>;
-    readonly instances: NodeInstances<Type>;
-    readonly node: ModelNode<Type>;
-    readonly defaultValue: NodeDefaultValue<Type>;
+    constructor(bind: BindDefinition);
 }
-export type AnyNodeDefinition = RootDefinition | AnyRepeatRangeDefinition | RepeatTemplateDefinition | RepeatInstanceDefinition | SubtreeDefinition | LeafNodeDefinition;
-export type TypedNodeDefinition<Type> = Extract<AnyNodeDefinition, {
-    readonly type: Type;
-}>;
+export type AnyNodeDefinition = RootDefinition | AnyRepeatDefinition | SubtreeDefinition | LeafNodeDefinition;

package/dist/parse/model/NoteNodeDefinition.d.ts

@@ -1,3 +1,5 @@
+import { ValueType } from '../../client/ValueType.ts';
+import { StaticLeafElement } from '../../integration/xpath/static-dom/StaticElement.ts';
 import { AnyBodyElementDefinition } from '../body/BodyDefinition.ts';
 import { InputControlDefinition } from '../body/control/InputControlDefinition.ts';
 import { BindComputationExpression } from '../expression/BindComputationExpression.ts';
@@ -8,7 +10,7 @@ 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 {
+export interface NoteBindDefinition<V extends ValueType> extends BindDefinition<V> {
     readonly readonly: NoteReadonlyDefinition;
 }
 export type NoteTextDefinition = LabelDefinition | HintDefinition;
@@ -21,10 +23,10 @@ export type NoteTextDefinition = LabelDefinition | HintDefinition;
  * 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;
+export declare class NoteNodeDefinition<V extends ValueType = ValueType> extends LeafNodeDefinition<V> {
+    readonly bind: NoteBindDefinition<V>;
     readonly bodyElement: InputControlDefinition;
     readonly noteTextDefinition: NoteTextDefinition;
-    static from(parent: ParentNodeDefinition, bind: BindDefinition, bodyElement: AnyBodyElementDefinition | null, node: Element): NoteNodeDefinition | null;
-    constructor(parent: ParentNodeDefinition, bind: NoteBindDefinition, bodyElement: InputControlDefinition, noteTextDefinition: NoteTextDefinition, node: Element);
+    static from<V extends ValueType>(parent: ParentNodeDefinition, bind: BindDefinition<V>, bodyElement: AnyBodyElementDefinition | null, node: StaticLeafElement): NoteNodeDefinition<V> | null;
+    constructor(parent: ParentNodeDefinition, bind: NoteBindDefinition<V>, bodyElement: InputControlDefinition, noteTextDefinition: NoteTextDefinition, template: StaticLeafElement);
 }

package/dist/parse/model/RangeNodeDefinition.d.ts

@@ -0,0 +1,42 @@
+import { ValueType } from '../../client/ValueType.ts';
+import { StaticLeafElement } from '../../integration/xpath/static-dom/StaticElement.ts';
+import { RuntimeValue } from '../../lib/codecs/getSharedValueCodec.ts';
+import { RangeControlBoundsDefinition, RangeControlDefinition } from '../body/control/RangeControlDefinition.ts';
+import { BindDefinition } from './BindDefinition.ts';
+import { LeafNodeDefinition } from './LeafNodeDefinition.ts';
+import { ParentNodeDefinition } from './NodeDefinition.ts';
+declare const RANGE_VALUE_TYPES: readonly ["decimal", "int"];
+export type RangeValueType = (typeof RANGE_VALUE_TYPES)[number];
+export interface RangeLeafNodeDefinition<V extends ValueType = ValueType> extends LeafNodeDefinition<V> {
+    readonly bodyElement: RangeControlDefinition;
+}
+declare class RangeNodeBoundsDefinition<V extends RangeValueType = RangeValueType> {
+    readonly min: NonNullable<RuntimeValue<V>>;
+    readonly max: NonNullable<RuntimeValue<V>>;
+    readonly step: NonNullable<RuntimeValue<V>>;
+    static from<V extends RangeValueType>(bounds: RangeControlBoundsDefinition, bind: BindDefinition<V>): RangeNodeBoundsDefinition<V>;
+    constructor(min: NonNullable<RuntimeValue<V>>, max: NonNullable<RuntimeValue<V>>, step: NonNullable<RuntimeValue<V>>);
+}
+/**
+ * @todo We should really consider making `LeafNodeDefinition` an abstract base
+ * class, and each node's definition an explicit concrete subclass of that. It
+ * would simplify a lot of things, reduce redundancy (and drift!) between
+ * various like `*Definition` types, and allow us to reason more clearly about
+ * what parse-product-input is used to construct each primary instance node.
+ * Furthermore, it would give us a great deal more flexibility to revisit some
+ * of the weaker parts of our current data model (e.g. splitting up selects).
+ *
+ * I explored this refactor as part of the prerequisite work to support range
+ * controls. I eventually backed out because it involved more churn than I felt
+ * comfortable with, but I do think we should keep an eye out for other
+ * opportunities to take on the churn.
+ */
+export declare class RangeNodeDefinition<V extends RangeValueType = RangeValueType> extends LeafNodeDefinition<V> implements RangeLeafNodeDefinition<V> {
+    readonly bind: BindDefinition<V>;
+    readonly bodyElement: RangeControlDefinition;
+    static from<V extends ValueType>(parent: ParentNodeDefinition, bind: BindDefinition<V>, bodyElement: RangeControlDefinition, node: StaticLeafElement): RangeNodeDefinition<Extract<V, RangeValueType>>;
+    readonly bounds: RangeNodeBoundsDefinition<V>;
+    private constructor();
+}
+export type AnyRangeNodeDefinition = RangeNodeDefinition<'decimal'> | RangeNodeDefinition<'int'>;
+export {};

package/dist/parse/model/RepeatDefinition.d.ts

@@ -0,0 +1,62 @@
+import { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
+import { NamespaceDeclarationMap } from '../../lib/names/NamespaceDeclarationMap.ts';
+import { QualifiedName } from '../../lib/names/QualifiedName.ts';
+import { RepeatElementDefinition } from '../body/RepeatElementDefinition.ts';
+import { RepeatCountControlExpression } from '../expression/RepeatCountControlExpression.ts';
+import { BindDefinition } from './BindDefinition.ts';
+import { DescendentNodeDefinition } from './DescendentNodeDefinition.ts';
+import { ChildNodeDefinition, ParentNodeDefinition } from './NodeDefinition.ts';
+export type RepeatInstanceNodes = readonly [StaticElement, ...StaticElement[]];
+export interface ControlledRepeatDefinition extends RepeatDefinition {
+    readonly count: RepeatCountControlExpression;
+}
+export interface UncontrolledRepeatDefinition extends RepeatDefinition {
+    readonly count: null;
+}
+/**
+ * Represents a definition of the combined concepts colloquially called a
+ * "repeat", as defined by a form, where those concepts include:
+ *
+ * - A {@link RepeatElementDefinition}—corresponding to a `<repeat>` {@link https://getodk.github.io/xforms-spec/#body-elements | body element}—which is associated with the nodeset referencing the "repeat template" and
+ *   all "repeat instances" (see below points describing both concepts in more detail). The presence of such a body element determines whether to produce a repeat definition (rather than e.g. a {@link SubtreeDefinition}).
+ *
+ * - A "repeat template", defined by a form either
+ *   explicitly,
+ *   or derived from the structure of the first form-defined "repeat instance"
+ *   (as described in the next point).
+ *
+ * - A sequence of one or more model instance nodes, each representing a "repeat instance"
+ *   defined by the form. These nodes contribute to the definition in the following ways:
+ *
+ *   - If an explicit "repeat template" is not defined for
+ *   the "repeat", one is derived from the **structure** (but not the values!)
+ *   of the first such model instance node.
+ *
+ *   - If the "repeat" is {@link ControlledRepeatDefinition | controlled} (i.e. by either a `jr:count` or `jr:noAddRemove` {@link https://getodk.github.io/xforms-spec/#body-attributes | attribute} on the associated {@link RepeatElementDefinition}
+ *
+ * (For construction of this
+ * definition, all other referenced instance nodes are **consumed** in the
+ * process of building the repeat definition's subtree of a
+ * {@link RootDefinition}, ensuring that one repeat definition is produced for
+ * all applicable nodes; they are later referenced for construction of a
+ * form's {@link PrimaryInstance | instance state}.)
+ *
+ * Combined, these concepts produce the details required to instantiate the
+ * {@link RepeatRange} and {@link RepeatInstance} instance state nodes
+ * associated with a defined repeat.
+ */
+export declare class RepeatDefinition extends DescendentNodeDefinition<'repeat', RepeatElementDefinition> {
+    static from(parent: ParentNodeDefinition, bind: BindDefinition, bodyElement: RepeatElementDefinition, instanceNodes: RepeatInstanceNodes): AnyRepeatDefinition;
+    readonly type = "repeat";
+    readonly children: readonly ChildNodeDefinition[];
+    readonly count: RepeatCountControlExpression | null;
+    readonly template: StaticElement;
+    readonly namespaceDeclarations: NamespaceDeclarationMap;
+    readonly qualifiedName: QualifiedName;
+    private constructor();
+    isControlled(): this is ControlledRepeatDefinition;
+    isUncontrolled(): this is UncontrolledRepeatDefinition;
+    omitTemplate(instanceNodes: readonly StaticElement[]): readonly StaticElement[];
+    toJSON(): object;
+}
+export type AnyRepeatDefinition = ControlledRepeatDefinition | UncontrolledRepeatDefinition;

package/dist/parse/model/RootAttributeDefinition.d.ts

@@ -0,0 +1,21 @@
+import { NamedNodeDefinition } from '../../lib/names/NamespaceDeclarationMap.ts';
+import { QualifiedName } from '../../lib/names/QualifiedName.ts';
+import { RootDefinition } from './RootDefinition.ts';
+interface RootAttributeSource {
+    readonly qualifiedName: QualifiedName;
+    readonly value: string;
+}
+/**
+ * @todo This class is named and typed to emphasize its intentionally narrow
+ * usage and purpose. It **intentionally** avoids addressing the much broader
+ * set of concerns around modeling attributes in primary instance/submissions.
+ */
+export declare class RootAttributeDefinition implements NamedNodeDefinition {
+    private readonly serializedXML;
+    readonly parent: RootDefinition;
+    readonly qualifiedName: QualifiedName;
+    readonly value: string;
+    constructor(root: RootDefinition, source: RootAttributeSource);
+    serializeAttributeXML(): string;
+}
+export {};

package/dist/parse/model/RootAttributeMap.d.ts

@@ -0,0 +1,24 @@
+import { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
+import { QualifiedName } from '../../lib/names/QualifiedName.ts';
+import { RootAttributeDefinition } from './RootAttributeDefinition.ts';
+import { RootDefinition } from './RootDefinition.ts';
+/**
+ * @todo This can be trivially expanded to a narrowly general case when we
+ * prioritize work to
+ * {@link https://github.com/getodk/web-forms/issues/285 | support attributes}
+ * (as modeled form nodes on par with elements). It's been deferred here to
+ * avoid expanding scope of an already fairly large yak shave.
+ *
+ * @todo There's a **much more expansive** general case just waiting for a good
+ * opportuntity to prioritize it. E.g. a `NamedNodeMap<T>`, where T is any
+ * generalized concept of a named node. This expansive generalization would have
+ * a ton of value in a variety of known performance optimization
+ * targets/solutions (i.e. optimizing the most redundant, suboptimal, frequently
+ * performed aspects of any typical XPath expression in a typical XForm).
+ *
+ * @see {@link QualifiedName} for more detail.
+ */
+export declare class RootAttributeMap extends Map<QualifiedName, RootAttributeDefinition> {
+    static from(root: RootDefinition, instanceNode: StaticElement): RootAttributeMap;
+    private constructor();
+}

package/dist/parse/model/RootDefinition.d.ts

@@ -1,27 +1,28 @@
+import { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
+import { NamespaceDeclarationMap } from '../../lib/names/NamespaceDeclarationMap.ts';
+import { QualifiedName } from '../../lib/names/QualifiedName.ts';
 import { BodyClassList } from '../body/BodyDefinition.ts';
 import { XFormDefinition } from '../XFormDefinition.ts';
-import { BindDefinition } from './BindDefinition.ts';
-import { FormSubmissionDefinition } from './FormSubmissionDefinition.ts';
 import { ModelDefinition } from './ModelDefinition.ts';
-import { ChildNodeDefinition, NodeDefinition, ParentNodeDefinition } from './NodeDefinition.ts';
-export declare class RootDefinition implements NodeDefinition<'root'> {
+import { ChildNodeDefinition, ParentNodeDefinition, NodeDefinition } from './NodeDefinition.ts';
+import { RootAttributeMap } from './RootAttributeMap.ts';
+import { SubmissionDefinition } from './SubmissionDefinition.ts';
+export declare class RootDefinition extends NodeDefinition<'root'> {
     protected readonly form: XFormDefinition;
     protected readonly model: ModelDefinition;
-    readonly submission: FormSubmissionDefinition;
+    readonly submission: SubmissionDefinition;
     readonly classes: BodyClassList;
     readonly type = "root";
-    readonly bind: BindDefinition;
-    readonly nodeset: string;
-    readonly nodeName: string;
+    readonly qualifiedName: QualifiedName;
     readonly bodyElement: null;
     readonly root: this;
     readonly parent: null;
+    readonly template: StaticElement;
+    readonly namespaceDeclarations: NamespaceDeclarationMap;
+    readonly attributes: RootAttributeMap;
     readonly children: readonly ChildNodeDefinition[];
-    readonly instances: null;
-    readonly node: Element;
-    readonly defaultValue: null;
     readonly isTranslated = false;
-    constructor(form: XFormDefinition, model: ModelDefinition, submission: FormSubmissionDefinition, classes: BodyClassList);
-    buildSubtree(parent: ParentNodeDefinition): readonly ChildNodeDefinition[];
-    toJSON(): Omit<this, "form" | "toJSON" | "bind" | "model" | "root" | "bodyElement" | "buildSubtree">;
+    constructor(form: XFormDefinition, model: ModelDefinition, submission: SubmissionDefinition, classes: BodyClassList);
+    buildSubtree(parent: ParentNodeDefinition, node: StaticElement): readonly ChildNodeDefinition[];
+    toJSON(): Omit<this, "form" | "toJSON" | "bind" | "root" | "model" | "bodyElement" | "buildSubtree">;
 }

package/dist/parse/model/SecondaryInstance/SecondaryInstancesDefinition.d.ts

@@ -1,8 +1,21 @@
-import { XFormsSecondaryInstanceMap } from '@getodk/xpath';
+import { XFORMS_KNOWN_ATTRIBUTE, XFORMS_LOCAL_NAME, XFormsSecondaryInstanceMap } from '@getodk/xpath';
 import { EngineXPathNode } from '../../../integration/xpath/adapter/kind.ts';
+import { StaticDocument } from '../../../integration/xpath/static-dom/StaticDocument.ts';
+import { StaticElement } from '../../../integration/xpath/static-dom/StaticElement.ts';
 import { XFormDOM } from '../../XFormDOM.ts';
-import { SecondaryInstanceRootDefinition } from './SecondaryInstanceRootDefinition.ts';
 import { ExternalSecondaryInstanceResourceLoadOptions } from './sources/ExternalSecondaryInstanceResource.ts';
+export interface SecondaryInstanceDefinition extends StaticDocument {
+    readonly rootDocument: SecondaryInstanceDefinition;
+    readonly root: SecondaryInstanceRootDefinition;
+}
+export interface SecondaryInstanceRootDefinition extends StaticElement {
+    readonly [XFORMS_LOCAL_NAME]: 'instance';
+    readonly [XFORMS_KNOWN_ATTRIBUTE]: 'id';
+    readonly rootDocument: SecondaryInstanceDefinition;
+    readonly root: SecondaryInstanceRootDefinition;
+    getAttributeValue(localName: 'id'): string;
+    getAttributeValue(localName: string): string | null;
+}
 export declare class SecondaryInstancesDefinition extends Map<string, SecondaryInstanceRootDefinition> implements XFormsSecondaryInstanceMap<EngineXPathNode> {
     /**
      * @package Only to be used for testing

package/dist/parse/model/SecondaryInstance/assertSecondaryInstanceDefinition.d.ts

@@ -0,0 +1,5 @@
+import { StaticDocument } from '../../../integration/xpath/static-dom/StaticDocument.ts';
+import { SecondaryInstanceDefinition } from './SecondaryInstancesDefinition.ts';
+type AssertSecondaryInstanceDefinition = (doc: StaticDocument) => asserts doc is SecondaryInstanceDefinition;
+export declare const assertSecondaryInstanceDefinition: AssertSecondaryInstanceDefinition;
+export {};

package/dist/parse/model/SecondaryInstance/defineSecondaryInstance.d.ts

@@ -0,0 +1,5 @@
+import { StaticElementOptions } from '../../../integration/xpath/static-dom/StaticElement.ts';
+import { SecondaryInstanceDefinition } from './SecondaryInstancesDefinition.ts';
+type SecondaryInstanceRoot = StaticElementOptions | '';
+export declare const defineSecondaryInstance: (instanceId: string, secondaryInstanceRoot: SecondaryInstanceRoot) => SecondaryInstanceDefinition;
+export {};

package/dist/parse/model/SecondaryInstance/sources/BlankSecondaryInstanceSource.d.ts

@@ -1,14 +1,8 @@
 import { JRResourceURL } from '../../../../../../common/src/jr-resources/JRResourceURL.ts';
 import { DOMSecondaryInstanceElement } from '../../../XFormDOM.ts';
-import { SecondaryInstanceDefinition } from '../SecondaryInstanceDefinition.ts';
+import { SecondaryInstanceDefinition } from '../SecondaryInstancesDefinition.ts';
 import { SecondaryInstanceSource } from './SecondaryInstanceSource.ts';
 export declare class BlankSecondaryInstanceSource extends SecondaryInstanceSource<'blank'> {
     constructor(instanceId: string, resourceURL: JRResourceURL, domElement: DOMSecondaryInstanceElement);
-    /**
-     * @todo there is really no sense in using the DOM for this, other than it was
-     * quicker/more ergonomic than constructing the requisite {@link StaticNode}
-     * structures directly. Pretty good sign those constructor signatures could
-     * use some TLC!
-     */
     parseDefinition(): SecondaryInstanceDefinition;
 }

package/dist/parse/model/SecondaryInstance/sources/CSVExternalSecondaryInstance.d.ts

@@ -1,4 +1,4 @@
-import { SecondaryInstanceDefinition } from '../SecondaryInstanceDefinition.ts';
+import { SecondaryInstanceDefinition } from '../SecondaryInstancesDefinition.ts';
 import { ExternalSecondaryInstanceSource } from './ExternalSecondaryInstanceSource.ts';
 export declare class CSVExternalSecondaryInstanceSource extends ExternalSecondaryInstanceSource<'csv'> {
     /**

package/dist/parse/model/SecondaryInstance/sources/GeoJSONExternalSecondaryInstance.d.ts

@@ -1,4 +1,4 @@
-import { SecondaryInstanceDefinition } from '../SecondaryInstanceDefinition.ts';
+import { SecondaryInstanceDefinition } from '../SecondaryInstancesDefinition.ts';
 import { ExternalSecondaryInstanceSource } from './ExternalSecondaryInstanceSource.ts';
 export declare class GeoJSONExternalSecondaryInstanceSource extends ExternalSecondaryInstanceSource<'geojson'> {
     parseDefinition(): SecondaryInstanceDefinition;

package/dist/parse/model/SecondaryInstance/sources/InternalSecondaryInstanceSource.d.ts

@@ -1,5 +1,5 @@
 import { DOMSecondaryInstanceElement } from '../../../XFormDOM.ts';
-import { SecondaryInstanceDefinition } from '../SecondaryInstanceDefinition.ts';
+import { SecondaryInstanceDefinition } from '../SecondaryInstancesDefinition.ts';
 import { SecondaryInstanceSource } from './SecondaryInstanceSource.ts';
 export declare class InternalSecondaryInstanceSource extends SecondaryInstanceSource<'internal'> {
     constructor(instanceId: string, resourceURL: null, domElement: DOMSecondaryInstanceElement);

package/dist/parse/model/SecondaryInstance/sources/SecondaryInstanceSource.d.ts

@@ -1,6 +1,6 @@
 import { JRResourceURL } from '../../../../../../common/src/jr-resources/JRResourceURL.ts';
 import { DOMSecondaryInstanceElement } from '../../../XFormDOM.ts';
-import { SecondaryInstanceDefinition } from '../SecondaryInstanceDefinition.ts';
+import { SecondaryInstanceDefinition } from '../SecondaryInstancesDefinition.ts';
 export type ExternalSecondaryInstanceSourceFormat = 'csv' | 'geojson' | 'xml';
 export type SecondaryInstanceSourceFormat = ExternalSecondaryInstanceSourceFormat | 'internal' | 'blank';
 export declare abstract class SecondaryInstanceSource<Format extends SecondaryInstanceSourceFormat = SecondaryInstanceSourceFormat> {

package/dist/parse/model/SecondaryInstance/sources/XMLExternalSecondaryInstanceSource.d.ts

@@ -1,4 +1,4 @@
-import { SecondaryInstanceDefinition } from '../SecondaryInstanceDefinition.ts';
+import { SecondaryInstanceDefinition } from '../SecondaryInstancesDefinition.ts';
 import { ExternalSecondaryInstanceSource } from './ExternalSecondaryInstanceSource.ts';
 export declare class XMLExternalSecondaryInstanceSource extends ExternalSecondaryInstanceSource<'xml'> {
     /**

package/dist/parse/model/{FormSubmissionDefinition.d.ts → SubmissionDefinition.d.ts}

@@ -1,6 +1,6 @@
-import { SubmissionDefinition } from '../../client/submission/SubmissionDefinition.ts';
+import { SubmissionMeta } from '../../client/submission/SubmissionMeta.ts';
 import { XFormDOM } from '../XFormDOM.ts';
-export declare class FormSubmissionDefinition implements SubmissionDefinition {
+export declare class SubmissionDefinition implements SubmissionMeta {
     readonly submissionAction: URL | null;
     readonly submissionMethod = "post";
     readonly encryptionKey: string | null;

package/dist/parse/model/SubtreeDefinition.d.ts

@@ -1,14 +1,16 @@
+import { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
+import { NamespaceDeclarationMap } from '../../lib/names/NamespaceDeclarationMap.ts';
+import { QualifiedName } from '../../lib/names/QualifiedName.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', AnyGroupElementDefinition | null> implements NodeDefinition<'subtree'> {
-    readonly node: Element;
+import { ChildNodeDefinition, ParentNodeDefinition } from './NodeDefinition.ts';
+export declare class SubtreeDefinition extends DescendentNodeDefinition<'subtree', AnyGroupElementDefinition | null> {
+    readonly template: StaticElement;
     readonly type = "subtree";
-    readonly nodeName: string;
+    readonly namespaceDeclarations: NamespaceDeclarationMap;
+    readonly qualifiedName: QualifiedName;
     readonly children: readonly ChildNodeDefinition[];
-    readonly instances: null;
-    readonly defaultValue: null;
-    constructor(parent: ParentNodeDefinition, bind: BindDefinition, bodyElement: AnyBodyElementDefinition | null, node: Element);
+    constructor(parent: ParentNodeDefinition, bind: BindDefinition, bodyElement: AnyBodyElementDefinition | null, template: StaticElement);
     toJSON(): Omit<this, "parent" | "toJSON" | "bind" | "root" | "bodyElement">;
 }

package/dist/parse/model/nodeDefinitionMap.d.ts

@@ -0,0 +1,5 @@
+import { AnyNodeDefinition } from './NodeDefinition.ts';
+import { RootDefinition } from './RootDefinition.ts';
+export type NodesetReference = string;
+export type NodeDefinitionMap = ReadonlyMap<NodesetReference, AnyNodeDefinition>;
+export declare const nodeDefinitionMap: (root: RootDefinition) => NodeDefinitionMap;

package/dist/parse/shared/parseInstanceXML.d.ts

@@ -0,0 +1,21 @@
+import { StaticDocument } from '../../integration/xpath/static-dom/StaticDocument.ts';
+import { ModelDefinition } from '../model/ModelDefinition.ts';
+/**
+ * Parses incoming instance XML input into a {@link StaticDocument}, preserving
+ * the form definition's default namespace URI (when the instance XML does not
+ * explicitly declare a default namespace).
+ *
+ * @todo This is a hack! A proper solution will involve extending namespace
+ * resolution (i.e. probably {@link NamespaceDeclarationMap}) from
+ * {@link RootDefinition} on down throughout the instance's {@link StaticNode}
+ * tree. The same will probably be the case for parsing (XML) external secondary
+ * instances as well, so at that point we can also stop using this specialized
+ * name!
+ *
+ * @todo Aside from this being a hack, it's not very robust because it makes
+ * assumptions which are _likely but definitely not guaranteed_!
+ *
+ * - Instance XML (probably) doeesn't declare a default namespace
+ * - Instance XML **definitely** declares non-default namespaces
+ */
+export declare const parseInstanceXML: (model: ModelDefinition, instanceXML: string) => StaticDocument;