@getodk/xforms-engine 0.6.0 → 0.8.0

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

@@ -2,10 +2,7 @@ import { NamedNodeDefinition } from '../../lib/names/NamespaceDeclarationMap.ts'
 import { QualifiedName } from '../../lib/names/QualifiedName.ts';
 import { RootDefinition } from './RootDefinition.ts';
 interface RootAttributeSource {
-    readonly namespaceURI: string | null;
-    readonly nodeName: string;
-    readonly prefix: string | null;
-    readonly localName: string;
+    readonly qualifiedName: QualifiedName;
     readonly value: string;
 }
 /**

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

@@ -1,3 +1,4 @@
+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';
@@ -18,6 +19,6 @@ import { RootDefinition } from './RootDefinition.ts';
  * @see {@link QualifiedName} for more detail.
  */
 export declare class RootAttributeMap extends Map<QualifiedName, RootAttributeDefinition> {
-    static from(root: RootDefinition, domRootSourceElement: Element): RootAttributeMap;
+    static from(root: RootDefinition, instanceNode: StaticElement): RootAttributeMap;
     private constructor();
 }

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

@@ -1,29 +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 { FormSubmissionDefinition } from './FormSubmissionDefinition.ts';
 import { ModelDefinition } from './ModelDefinition.ts';
 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 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" | "bind" | "model" | "toJSON" | "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,3 +1,4 @@
+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';
@@ -5,13 +6,11 @@ import { BindDefinition } from './BindDefinition.ts';
 import { DescendentNodeDefinition } from './DescendentNodeDefinition.ts';
 import { ChildNodeDefinition, ParentNodeDefinition } from './NodeDefinition.ts';
 export declare class SubtreeDefinition extends DescendentNodeDefinition<'subtree', AnyGroupElementDefinition | null> {
-    readonly node: Element;
+    readonly template: StaticElement;
     readonly type = "subtree";
     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);
-    toJSON(): Omit<this, "parent" | "bind" | "toJSON" | "root" | "bodyElement">;
+    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;

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

@@ -1,23 +1,6 @@
-import { AnyConstructor } from '../../../../common/types/helpers.js';
-import { StaticDocument, StaticDocumentRootFactory } from '../../integration/xpath/static-dom/StaticDocument.ts';
-import { StaticElementAttributesFactory, StaticElementChildNodesFactory, StaticElementOptions, StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
-import { StaticParentNode } from '../../integration/xpath/static-dom/StaticNode.ts';
-type ConcreteConstructor<T extends AnyConstructor> = Pick<T, keyof T>;
-export type ConcreteStaticDocumentConstructor<T extends StaticDocument<Root>, Root extends StaticElement> = ConcreteConstructor<typeof StaticDocument<Root>> & (new (rootFactory: StaticDocumentRootFactory<T, Root>) => T);
-declare const ELEMENT_NODE: 1, CDATA_SECTION_NODE: 4, TEXT_NODE: 3;
-interface StaticChildElementSource {
-    readonly domType: typeof ELEMENT_NODE;
-    readonly domNode: Element;
+import { StaticDocument } from '../../integration/xpath/static-dom/StaticDocument.ts';
+interface ParseStaticDocumentFromDOMSubtreeOptions {
+    readonly nodesetPrefix?: string;
 }
-interface StaticChildTextSource {
-    readonly domType: typeof CDATA_SECTION_NODE | typeof TEXT_NODE;
-    readonly domNode: CharacterData;
-}
-type StaticChildNodeSource = StaticChildElementSource | StaticChildTextSource;
-export declare const toStaticChildNodeSource: (childNode: ChildNode) => StaticChildNodeSource | null;
-export type StaticElementConstructor<T extends StaticElement<Parent>, Parent extends StaticParentNode = StaticParentNode> = ConcreteConstructor<typeof StaticElement> & {
-    readonly prototype: T;
-    new (parent: Parent, attributesFactory: StaticElementAttributesFactory, childNodesFactory: StaticElementChildNodesFactory, options: StaticElementOptions): T;
-};
-export declare const parseStaticDocumentFromDOMSubtree: <T extends StaticDocument<Root>, Root extends StaticElement<T>>(DocumentConstructor: ConcreteStaticDocumentConstructor<T, Root>, DocumentRootConstructor: StaticElementConstructor<Root, T>, subtreeRootElement: Element) => T;
+export declare const parseStaticDocumentFromDOMSubtree: (subtreeRootElement: Element, options?: ParseStaticDocumentFromDOMSubtreeOptions) => StaticDocument;
 export {};