@getodk/xforms-engine 0.5.0 → 0.6.0

package/src/instance/hierarchy.ts

@@ -1,26 +1,23 @@
 import type { Group } from './Group.ts';
 import type { AnyInputControl } from './InputControl.ts';
 import type { AnyModelValue } from './ModelValue.ts';
-import type { Note } from './Note.ts';
+import type { AnyNote } from './Note.ts';
 import type { PrimaryInstance } from './PrimaryInstance.ts';
+import type { AnyRangeControl } from './RangeControl.ts';
 import type { RepeatInstance } from './repeat/RepeatInstance.ts';
 import type { RepeatRangeControlled } from './repeat/RepeatRangeControlled.ts';
 import type { RepeatRangeUncontrolled } from './repeat/RepeatRangeUncontrolled.ts';
 import type { Root } from './Root.ts';
-import type { SelectField } from './SelectField.ts';
+import type { SelectControl } from './SelectControl.ts';
 import type { Subtree } from './Subtree.ts';
 import type { TriggerControl } from './TriggerControl.ts';
-import type { RangeControl } from './unsupported/RangeControl.ts';
-import type { RankControl } from './unsupported/RankControl.ts';
+import type { RankControl } from './RankControl.ts';
 import type { UploadControl } from './unsupported/UploadControl.ts';
 
 export type RepeatRange = RepeatRangeControlled | RepeatRangeUncontrolled;
 
 // prettier-ignore
-export type AnyUnsupportedControl =
-	| RangeControl
-	| RankControl
-	| UploadControl;
+export type AnyUnsupportedControl = UploadControl;
 
 // prettier-ignore
 export type AnyNode =
@@ -31,10 +28,12 @@ export type AnyNode =
 	| Subtree
 	| RepeatRange
 	| RepeatInstance
-	| Note
+	| AnyNote
 	| AnyModelValue
 	| AnyInputControl
-	| SelectField
+	| AnyRangeControl
+	| RankControl
+	| SelectControl
 	| TriggerControl
 	| AnyUnsupportedControl;
 
@@ -65,9 +64,11 @@ export type AnyChildNode =
 	| RepeatRange
 	| RepeatInstance
 	| AnyModelValue
-	| Note
+	| AnyNote
 	| AnyInputControl
-	| SelectField
+	| AnyRangeControl
+	| RankControl
+	| SelectControl
 	| TriggerControl
 	| AnyUnsupportedControl;
 
@@ -78,9 +79,11 @@ export type GeneralChildNode =
 	| Subtree
 	| RepeatRange
 	| AnyModelValue
-	| Note
+	| AnyNote
 	| AnyInputControl
-	| SelectField
+	| AnyRangeControl
+	| RankControl
+	| SelectControl
 	| TriggerControl
 	| AnyUnsupportedControl;
 
@@ -88,8 +91,10 @@ export type GeneralChildNode =
 export type AnyValueNode =
 	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
 	| AnyModelValue
-	| Note
+	| AnyNote
 	| AnyInputControl
-	| SelectField
+	| AnyRangeControl
+	| RankControl
+	| SelectControl
 	| TriggerControl
 	| AnyUnsupportedControl;

package/src/instance/internal-api/InstanceValueContext.ts

@@ -1,10 +1,12 @@
 import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
 import type { BindComputationExpression } from '../../parse/expression/BindComputationExpression.ts';
+import type { AnyBindPreloadDefinition } from '../../parse/model/BindPreloadDefinition.ts';
 import type { EvaluationContext } from './EvaluationContext.ts';
 
 export type DecodeInstanceValue = (value: string) => string;
 
 interface InstanceValueContextDefinitionBind {
+	readonly preload: AnyBindPreloadDefinition | null;
 	readonly calculate: BindComputationExpression<'calculate'> | null;
 	readonly readonly: BindComputationExpression<'readonly'>;
 }

package/src/instance/internal-api/submission/ClientReactiveSubmittableLeafNode.ts

@@ -1,4 +1,5 @@
 import type { SubmissionState } from '../../../client/submission/SubmissionState.ts';
+import type { QualifiedName } from '../../../lib/names/QualifiedName.ts';
 import type { EscapedXMLText } from '../../../lib/xml-serialization.ts';
 import type {
 	ClientReactiveSubmittableChildNode,
@@ -13,7 +14,7 @@ interface ClientReactiveSubmittableLeafNodeCurrentState<RuntimeValue> {
 export type SerializedSubmissionValue = string;
 
 interface ClientReactiveSubmittableLeafNodeDefinition {
-	readonly nodeName: string;
+	readonly qualifiedName: QualifiedName;
 }
 
 export interface ClientReactiveSubmittableLeafNode<RuntimeValue> {

package/src/instance/internal-api/submission/ClientReactiveSubmittableParentNode.ts

@@ -1,4 +1,5 @@
 import type { SubmissionState } from '../../../client/submission/SubmissionState.ts';
+import type { QualifiedName } from '../../../lib/names/QualifiedName.ts';
 
 export interface ClientReactiveSubmittableChildNode {
 	readonly submissionState: SubmissionState;
@@ -12,7 +13,7 @@ interface ClientReactiveSubmittableParentNodeCurrentState<
 }
 
 export interface ClientReactiveSubmittableParentNodeDefinition {
-	readonly nodeName: string;
+	readonly qualifiedName: QualifiedName;
 }
 
 export interface ClientReactiveSubmittableParentNode<

package/src/instance/internal-api/submission/ClientReactiveSubmittableValueNode.ts

@@ -1,4 +1,5 @@
 import type { SubmissionState } from '../../../client/submission/SubmissionState.ts';
+import type { QualifiedName } from '../../../lib/names/QualifiedName.ts';
 import type {
 	ClientReactiveSubmittableChildNode,
 	ClientReactiveSubmittableParentNode,
@@ -12,7 +13,7 @@ interface ClientReactiveSubmittableValueNodeCurrentState {
 export type SerializedSubmissionValue = string;
 
 interface ClientReactiveSubmittableValueNodeDefinition {
-	readonly nodeName: string;
+	readonly qualifiedName: QualifiedName;
 }
 
 export interface ClientReactiveSubmittableValueNode {

package/src/instance/repeat/BaseRepeatRange.ts

@@ -143,6 +143,8 @@ export abstract class BaseRepeatRange<Definition extends AnyRepeatRangeDefinitio
 	 */
 	abstract override readonly appearances: NodeAppearances<Definition>;
 
+	readonly nodeOptions = null;
+
 	readonly currentState: MaterializedChildren<CurrentState<RepeatRangeStateSpec>, RepeatInstance>;
 
 	abstract override readonly validationState: AncestorNodeValidationState;

package/src/instance/repeat/RepeatInstance.ts

@@ -92,6 +92,7 @@ export class RepeatInstance
 	 * @see {@link RepeatRange.appearances}
 	 */
 	readonly appearances: RepeatInstanceNodeAppearances;
+	readonly nodeOptions = null;
 
 	readonly currentState: MaterializedChildren<
 		CurrentState<RepeatInstanceStateSpec>,

package/src/instance/resource.ts

@@ -10,7 +10,10 @@ export interface ResourceOptions {
 }
 
 const fetchTextFromURL = async (resource: URL, options: ResourceOptions): Promise<string> => {
-	const response = await options.fetchResource(resource);
+	// destructuring prevents "Failed to execute 'fetch' on 'Window': Illegal invocation"
+	const { fetchResource } = options;
+
+	const response = await fetchResource(resource);
 
 	return response.text();
 };

package/src/integration/xpath/adapter/names.ts

@@ -15,49 +15,54 @@ import {
 	XHTML_NAMESPACE_URI,
 } from '@getodk/common/constants/xmlns.ts';
 import { XPathFunctionalityNotSupportedError } from '../../../error/XPathFunctionalityNotSupportedError.ts';
-import type { InstanceNode } from '../../../instance/abstract/InstanceNode.ts';
-import type { StaticNode } from '../static-dom/StaticNode.ts';
+import type { AnyStaticNode } from '../static-dom/StaticNode.ts';
 import type { EngineXPathNode } from './kind.ts';
-import type { getNamespaceDeclarations } from './traversal.ts';
 
 export const getEngineXPathNodeNamespaceURI = (node: EngineXPathNode): string | null => {
 	switch (node.nodeType) {
 		case 'primary-instance':
+		case 'static-document':
 		case 'static-text':
+		case 'repeat-range:controlled':
+		case 'repeat-range:uncontrolled':
 			return null;
 
 		case 'static-attribute':
 		case 'static-element':
-			return node.namespaceURI;
+			return node.qualifiedName.namespaceURI?.href ?? null;
 
 		default:
-			return XFORMS_NAMESPACE_URI;
+			return node.definition.qualifiedName.namespaceURI?.href ?? null;
 	}
 };
 
-/**
- * @todo currently, neither {@link InstanceNode} nor {@link StaticNode} account
- * for prefixes in qualified names. This was already a general enough gap that
- * it makes sense to defer to a broader solution as it becomes a priority
- * (likely prompted by a bug report about unexpected behavior of the XPath
- * `name` function).
- */
 export const getEngineXPathNodeQualifiedName = (node: EngineXPathNode): string => {
-	return getEngineXPathNodeLocalName(node);
+	switch (node.nodeType) {
+		case 'static-attribute':
+		case 'static-element':
+			return node.qualifiedName.getPrefixedName();
+
+		case 'static-document':
+		case 'static-text':
+			return '';
+
+		default:
+			return node.definition.qualifiedName.getPrefixedName();
+	}
 };
 
 export const getEngineXPathNodeLocalName = (node: EngineXPathNode): string => {
 	switch (node.nodeType) {
 		case 'static-attribute':
 		case 'static-element':
-			return node.localName;
+			return node.qualifiedName.localName;
 
 		case 'static-document':
 		case 'static-text':
 			return '';
 
 		default:
-			return node.definition.nodeName;
+			return node.definition.qualifiedName.localName;
 	}
 };
 
@@ -65,9 +70,23 @@ export const getEngineProcessingInstructionName =
 	XPathFunctionalityNotSupportedError.createStubImplementation('processing-instruction');
 
 /**
- * @todo @see {@link getNamespaceDeclarations}
+ * @todo in most cases we should not have **custom** namespace resolution from a
+ * static node (e.g. external secondary instance, itext translation) context.
+ * The main exception to that would be _XML external secondary instances_, which
+ * of course can declare arbitrary namespaces on any arbitrary subtree, just
+ * like a form definition's XML. In all other cases, we'd want to resolve a
+ * prefix here from the _primary instance_ context. However, we don't (yet) have
+ * access to the primary instance context from a static node. So we currently
+ * fall back to the previous (incomplete/potentially wrong) default mapping.
+ *
+ * Note that this is relatively safe for the general case, and only potentially
+ * wrong for:
+ *
+ * 1. Forms authored as XML, with arbitrary/non-default namespace declarations
+ * 2. XML external secondary instances, also with arbitrary/non-default
+ *    namespace declarations
  */
-export const resolveEngineXPathNodeNamespaceURI = (_: EngineXPathNode, prefix: string | null) => {
+const resolveNamespaceURIFromStaticNodeContext = (_: AnyStaticNode, prefix: string | null) => {
 	switch (prefix) {
 		case null:
 			return XFORMS_NAMESPACE_URI;
@@ -97,3 +116,33 @@ export const resolveEngineXPathNodeNamespaceURI = (_: EngineXPathNode, prefix: s
 			return null;
 	}
 };
+
+export const resolveEngineXPathNodeNamespaceURI = (
+	node: EngineXPathNode,
+	prefix: string | null
+): string | null => {
+	switch (node.nodeType) {
+		case 'static-attribute':
+		case 'static-document':
+		case 'static-element':
+		case 'static-text':
+			return resolveNamespaceURIFromStaticNodeContext(node, prefix);
+
+		case 'group':
+		case 'input':
+		case 'model-value':
+		case 'note':
+		case 'primary-instance':
+		case 'range':
+		case 'rank':
+		case 'repeat-instance':
+		case 'repeat-range:controlled':
+		case 'repeat-range:uncontrolled':
+		case 'root':
+		case 'select':
+		case 'subtree':
+		case 'trigger':
+		case 'upload':
+			return node.definition.namespaceDeclarations.get(prefix)?.declaredURI?.href ?? null;
+	}
+};

package/src/integration/xpath/adapter/traversal.ts

@@ -27,16 +27,17 @@ export const getEngineXPathAttributes = (node: EngineXPathNode): Iterable<Engine
 };
 
 /**
- * @todo XML XForms may actually define explicit namespace declarations on
- * non-root elements (i.e. elements other than the form definition's `h:html`,
- * itext `translation`, secondary `instance`). Expressions defined in such forms
- * may also expect to use those namespace declarations. It would even seem
- * likely! Why declare namespaces on a subtree if you don't intend to use them?
- * We don't currently capture namespace declarations below `h:html` in the parse
- * stage (which, if we intend to support the use case, is where we should
- * start).
+ * @todo We've now laid most of the groundwork necessary to implement this
+ * properly. At time of writing it has still been deferred because:
  *
- * @todo At the very least, we should probably produce a set of default namespace declarations. At least for `h:html`, maybe for other "root" nodes.
+ * 1. The scope of changes enabling it is already a fairly large yak shave.
+ * 2. It is only used to support XPath LocationPath Steps whose AxisName is
+ *    `namespace`. If we _ever_ support this, it would probably be for extremely
+ *    niche use cases!
+ *
+ * @todo Since we've consciously deferred implementing this (twice now!), should
+ * it throw? It might be nice to be alerted if the assumptions in point 2 above
+ * are somehow wrong (or become wrong).
  */
 export const getNamespaceDeclarations = (): Iterable<never> => [];
 

package/src/integration/xpath/static-dom/StaticAttribute.ts

@@ -1,28 +1,36 @@
 import { XPathNodeKindKey } from '@getodk/xpath';
+import { QualifiedName } from '../../../lib/names/QualifiedName.ts';
 import type { XFormsXPathAttribute } from '../adapter/XFormsXPathNode.ts';
+import type { StaticDocument } from './StaticDocument.ts';
 import type { StaticElement } from './StaticElement.ts';
-import type { StaticNamedNodeOptions } from './StaticNamedNode.ts';
-import { StaticNamedNode } from './StaticNamedNode.ts';
+import { StaticNode } from './StaticNode.ts';
 
-interface StaticAttributeOptions extends StaticNamedNodeOptions {
+interface StaticAttributeOptions {
+	readonly namespaceURI: string | null;
+	readonly prefix?: string | null;
+	readonly localName: string;
 	readonly value: string;
 }
 
-export class StaticAttribute extends StaticNamedNode<'attribute'> implements XFormsXPathAttribute {
+export class StaticAttribute extends StaticNode<'attribute'> implements XFormsXPathAttribute {
 	readonly [XPathNodeKindKey] = 'attribute';
 	readonly nodeType = 'static-attribute';
+	readonly rootDocument: StaticDocument;
 	readonly root: StaticElement;
+	readonly qualifiedName: QualifiedName;
 	readonly attributes = [] as const;
 	readonly children = null;
-	override readonly value: string;
+	readonly value: string;
 
 	constructor(
-		override readonly parent: StaticElement,
+		readonly parent: StaticElement,
 		options: StaticAttributeOptions
 	) {
-		super(parent, options);
+		super();
 
+		this.rootDocument = parent.rootDocument;
 		this.root = parent.root;
+		this.qualifiedName = new QualifiedName(options);
 		this.value = options.value;
 	}
 

package/src/integration/xpath/static-dom/StaticDocument.ts

@@ -15,7 +15,6 @@ export abstract class StaticDocument<DocumentRoot extends StaticElement = Static
 	readonly nodeType = 'static-document';
 	readonly rootDocument: StaticDocument;
 	readonly root: DocumentRoot;
-	readonly isXFormsNamespace: boolean;
 	readonly parent = null;
 	readonly children: readonly [root: DocumentRoot];
 
@@ -27,7 +26,6 @@ export abstract class StaticDocument<DocumentRoot extends StaticElement = Static
 		const root = rootFactory(this);
 
 		this.root = root;
-		this.isXFormsNamespace = root.isXFormsNamespace;
 		this.children = [root];
 	}
 

package/src/integration/xpath/static-dom/StaticElement.ts

@@ -1,16 +1,21 @@
 import { XFORMS_KNOWN_ATTRIBUTE, XFORMS_LOCAL_NAME, XPathNodeKindKey } from '@getodk/xpath';
+import { QualifiedName } from '../../../lib/names/QualifiedName.ts';
 import type { EngineDOMAdapter } from '../adapter/engineDOMAdapter.ts';
 import type { XFormsXPathElement } from '../adapter/XFormsXPathNode.ts';
 import { StaticAttribute } from './StaticAttribute.ts';
-import type { StaticNamedNodeOptions } from './StaticNamedNode.ts';
-import { StaticNamedNode } from './StaticNamedNode.ts';
+import type { StaticDocument } from './StaticDocument.ts';
 import type { StaticChildNode, StaticParentNode } from './StaticNode.ts';
+import { StaticNode } from './StaticNode.ts';
 
 export type StaticElementAttributesFactory = (element: StaticElement) => readonly StaticAttribute[];
 
 export type StaticElementChildNodesFactory = (element: StaticElement) => readonly StaticChildNode[];
 
-export interface StaticElementOptions extends StaticNamedNodeOptions {}
+export interface StaticElementOptions {
+	readonly namespaceURI: string | null;
+	readonly prefix?: string | null;
+	readonly localName: string;
+}
 
 type StaticElementKnownAttributeValue<
 	T extends StaticElement,
@@ -34,7 +39,7 @@ const assertStaticElementKnownAttributeValue: AssertStaticElementKnownAttributeV
 };
 
 export class StaticElement<Parent extends StaticParentNode = StaticParentNode>
-	extends StaticNamedNode<'element'>
+	extends StaticNode<'element'>
 	implements XFormsXPathElement
 {
 	readonly [XFORMS_LOCAL_NAME]?: string;
@@ -42,25 +47,33 @@ export class StaticElement<Parent extends StaticParentNode = StaticParentNode>
 
 	readonly [XPathNodeKindKey] = 'element';
 	readonly nodeType = 'static-element';
+	readonly rootDocument: StaticDocument;
 	readonly root: StaticElement;
+	readonly qualifiedName: QualifiedName;
 	readonly attributes: readonly StaticAttribute[];
 	readonly children: readonly StaticChildNode[];
+	readonly value = null;
 
 	constructor(
-		parent: Parent,
+		readonly parent: Parent,
 		attributesFactory: StaticElementAttributesFactory,
 		childNodesFactory: StaticElementChildNodesFactory,
 		options: StaticElementOptions
 	) {
-		super(parent, options);
+		super();
+
+		const { rootDocument } = parent;
+
+		this.rootDocument = rootDocument;
 
 		// Account for the fact that we may be constructing the document root!
-		if (parent === this.rootDocument) {
+		if (parent === rootDocument) {
 			this.root = this;
 		} else {
 			this.root = parent.root;
 		}
 
+		this.qualifiedName = new QualifiedName(options);
 		this.attributes = attributesFactory(this);
 		this.children = childNodesFactory(this);
 	}
@@ -73,7 +86,7 @@ export class StaticElement<Parent extends StaticParentNode = StaticParentNode>
 	protected getAttributeNode(localName: string): StaticAttribute | null {
 		return (
 			this.attributes.find((attribute) => {
-				return attribute.localName === localName;
+				return attribute.qualifiedName.localName === localName;
 			}) ?? null
 		);
 	}

package/src/lib/client-reactivity/submission/createLeafNodeSubmissionState.ts

@@ -14,7 +14,7 @@ export const createLeafNodeSubmissionState = <Value>(
 			const value = node.encodeValue(node.currentState.value);
 			const xmlValue = escapeXMLText(value);
 
-			return serializeLeafElementXML(node.definition.nodeName, xmlValue);
+			return serializeLeafElementXML(node.definition.qualifiedName, xmlValue);
 		},
 	};
 };

package/src/lib/client-reactivity/submission/createParentNodeSubmissionState.ts

@@ -16,7 +16,7 @@ export const createParentNodeSubmissionState = (
 				return child.submissionState.submissionXML;
 			});
 
-			return serializeParentElementXML(node.definition.nodeName, serializedChildren);
+			return serializeParentElementXML(node.definition.qualifiedName, serializedChildren);
 		},
 	};
 };

package/src/lib/client-reactivity/submission/createRootSubmissionState.ts

@@ -0,0 +1,19 @@
+import type { SubmissionState } from '../../../client/submission/SubmissionState.ts';
+import type { Root } from '../../../instance/Root.ts';
+import { serializeParentElementXML } from '../../xml-serialization.ts';
+
+export const createRootSubmissionState = (node: Root): SubmissionState => {
+	return {
+		get submissionXML() {
+			const { namespaceDeclarations, attributes } = node.definition;
+			const serializedChildren = node.currentState.children.map((child) => {
+				return child.submissionState.submissionXML;
+			});
+
+			return serializeParentElementXML(node.definition.qualifiedName, serializedChildren, {
+				namespaceDeclarations,
+				attributes: Array.from(attributes.values()),
+			});
+		},
+	};
+};

package/src/lib/client-reactivity/submission/createValueNodeSubmissionState.ts

@@ -5,7 +5,7 @@ import { escapeXMLText, serializeLeafElementXML } from '../../xml-serialization.
 export const createValueNodeSubmissionState = (
 	node: ClientReactiveSubmittableValueNode
 ): SubmissionState => {
-	const { nodeName } = node.definition;
+	const { qualifiedName } = node.definition;
 
 	return {
 		get submissionXML() {
@@ -15,7 +15,7 @@ export const createValueNodeSubmissionState = (
 
 			const xmlValue = escapeXMLText(node.currentState.instanceValue);
 
-			return serializeLeafElementXML(nodeName, xmlValue);
+			return serializeLeafElementXML(qualifiedName, xmlValue);
 		},
 	};
 };