@getodk/xforms-engine 0.4.0 → 0.6.0

package/src/parse/model/BindTypeDefinition.ts

@@ -0,0 +1,175 @@
+import { XSD_NAMESPACE_URI, XSD_PREFIX } from '@getodk/common/constants/xmlns.ts';
+import { parseQualifiedNameExpression } from '../xpath/semantic-analysis.ts';
+import type { BindElement } from './BindElement.ts';
+
+/**
+ * As specified by {@link https://getodk.github.io/xforms-spec/#bind-attributes}
+ */
+export const DEFAULT_BIND_TYPE = 'string';
+
+export type DefaultBindType = typeof DEFAULT_BIND_TYPE;
+
+/**
+ * As specified by {@link https://getodk.github.io/xforms-spec/#data-types}
+ */
+const BIND_TYPES = [
+	DEFAULT_BIND_TYPE,
+	'int',
+	'boolean',
+	'decimal',
+	'date',
+	'time',
+	'dateTime',
+	'geopoint',
+	'geotrace',
+	'geoshape',
+	'binary',
+	'barcode',
+	'intent',
+] as const;
+
+type BindTypes = typeof BIND_TYPES;
+
+export type BindType = BindTypes[number];
+
+const isBindType = (value: string): value is BindType => {
+	return BIND_TYPES.includes(value as BindType);
+};
+
+const resolveSupportedBindType = (sourceType: string): BindType | null => {
+	return isBindType(sourceType) ? sourceType : null;
+};
+
+type BindTypeAliasMapping = Readonly<Record<string, BindType>>;
+
+/**
+ * @todo should we make these aliases explicit (rather than relying on {@link resolveUnsupportedBindType})?
+ *
+ * - select1
+ * - rank
+ * - odk:rank
+ */
+const BIND_TYPE_ALIASES: BindTypeAliasMapping = {
+	integer: 'int',
+};
+
+/**
+ * @todo Should this be marked deprecated?
+ * @todo Should we warn on alias resolution?
+ */
+const resolveAliasedBindType = (sourceType: string): BindType | null => {
+	return BIND_TYPE_ALIASES[sourceType] ?? null;
+};
+
+/**
+ * @todo Should we warn on this fallback?
+ */
+const resolveUnsupportedBindType = (_unsupportedType: string): BindType => {
+	return DEFAULT_BIND_TYPE;
+};
+
+interface BindDataTypeNamespaceResolver {
+	lookupNamespaceURI(prefix: string | null): string | null;
+	lookupPrefix(namespaceURI: string | null): string | null;
+}
+
+/**
+ * Resolves the XML Schema namespace prefix by:
+ *
+ * - Explicitly declared prefix, if any
+ * - Default to {@link XSD_PREFIX} _unless that prefix is bound to some other
+ *   namespace URI_
+ */
+const resolveXMLSchemaNamespacePrefix = (
+	resolver: BindDataTypeNamespaceResolver
+): string | null => {
+	const declaredPrefix = resolver.lookupPrefix(XSD_NAMESPACE_URI);
+
+	if (declaredPrefix != null) {
+		return declaredPrefix;
+	}
+
+	if (resolver.lookupNamespaceURI(XSD_PREFIX) == null) {
+		return XSD_PREFIX;
+	}
+
+	return null;
+};
+
+interface MaybeBindElementNamespaceResolver
+	extends BindElement,
+		Partial<BindDataTypeNamespaceResolver> {}
+
+interface BindElementNamespaceResolver extends BindElement, BindDataTypeNamespaceResolver {}
+
+const isNamespaceResolver = (
+	bindElement: MaybeBindElementNamespaceResolver
+): bindElement is BindElementNamespaceResolver => {
+	return (
+		typeof bindElement.lookupNamespaceURI === 'function' &&
+		typeof bindElement.lookupPrefix === 'function'
+	);
+};
+
+const resolveNamespacedBindType = (
+	bindElement: BindElement,
+	sourceType: string
+): BindType | null => {
+	if (!isNamespaceResolver(bindElement)) {
+		return null;
+	}
+
+	const qualifiedName = parseQualifiedNameExpression(sourceType);
+
+	if (qualifiedName == null) {
+		return null;
+	}
+
+	const xsdPrefix = resolveXMLSchemaNamespacePrefix(bindElement);
+
+	if (xsdPrefix == null) {
+		return null;
+	}
+
+	const { prefix, localPart } = qualifiedName;
+
+	if (prefix === xsdPrefix) {
+		return (
+			resolveSupportedBindType(localPart) ??
+			resolveAliasedBindType(localPart) ??
+			resolveUnsupportedBindType(localPart)
+		);
+	}
+
+	return null;
+};
+
+const resolveBindType = (bindElement: BindElement, sourceType: string): BindType => {
+	return (
+		resolveSupportedBindType(sourceType) ??
+		resolveAliasedBindType(sourceType) ??
+		resolveNamespacedBindType(bindElement, sourceType) ??
+		resolveUnsupportedBindType(sourceType)
+	);
+};
+
+export class BindTypeDefinition<T extends BindType = BindType> {
+	static from<T extends BindType>(bindElement: BindElement): BindTypeDefinition<T> {
+		const sourceType = bindElement.getAttribute('type');
+
+		if (sourceType == null) {
+			return new this(sourceType, DEFAULT_BIND_TYPE);
+		}
+
+		const resolved = resolveBindType(bindElement, sourceType);
+
+		return new this(sourceType, resolved);
+	}
+
+	private constructor(source: null, resolved: DefaultBindType);
+	private constructor(source: string, resolved: BindType);
+	private constructor(
+		readonly source: string | null,
+		readonly resolved: T
+	) {}
+}

package/src/parse/model/DescendentNodeDefinition.ts

@@ -1,14 +1,7 @@
 import type { AnyBodyElementDefinition } from '../body/BodyDefinition.ts';
 import type { BindDefinition } from './BindDefinition.ts';
-import type {
-	ModelNode,
-	NodeChildren,
-	NodeDefaultValue,
-	NodeDefinition,
-	NodeDefinitionType,
-	NodeInstances,
-	NodeParent,
-} from './NodeDefinition.ts';
+import type { NodeDefinitionType, ParentNodeDefinition } from './NodeDefinition.ts';
+import { NodeDefinition } from './NodeDefinition.ts';
 import type { RootDefinition } from './RootDefinition.ts';
 
 export type DescendentNodeType = Exclude<NodeDefinitionType, 'root'>;
@@ -18,38 +11,21 @@ type DescendentNodeBodyElement = AnyBodyElementDefinition;
 export abstract class DescendentNodeDefinition<
 	Type extends DescendentNodeType,
 	BodyElement extends DescendentNodeBodyElement | null = DescendentNodeBodyElement | null,
-> implements NodeDefinition<Type>
-{
-	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;
-
+> extends NodeDefinition<Type> {
 	readonly root: RootDefinition;
-	readonly nodeset: string;
-	readonly dependencyExpressions: ReadonlySet<string>;
 	readonly isTranslated: boolean = false;
 
 	constructor(
-		readonly parent: NodeParent<Type>,
-		readonly bind: BindDefinition,
+		readonly parent: ParentNodeDefinition,
+		bind: BindDefinition,
 		readonly bodyElement: BodyElement
 	) {
+		super(bind);
+
 		this.root = parent.root;
-		this.nodeset = bind.nodeset;
 
 		if (bind.isTranslated || bodyElement?.isTranslated) {
 			this.isTranslated = true;
 		}
-
-		this.dependencyExpressions = new Set([
-			...bind.dependencyExpressions,
-			...(bodyElement?.dependencyExpressions ?? []),
-		]);
 	}
 }
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type AnyDescendantNodeDefinition = DescendentNodeDefinition<any, any>;

package/src/parse/model/FormSubmissionDefinition.ts

@@ -0,0 +1,44 @@
+import type { SubmissionDefinition } from '../../client/submission/SubmissionDefinition.ts';
+import { getSubmissionElement } from '../../lib/dom/query.ts';
+import type { XFormDOM } from '../XFormDOM.ts';
+
+export class FormSubmissionDefinition implements SubmissionDefinition {
+	readonly submissionAction!: URL | null;
+	readonly submissionMethod = 'post';
+	readonly encryptionKey!: string | null;
+
+	constructor(xformDOM: XFormDOM) {
+		const submissionElement = getSubmissionElement(xformDOM.model);
+
+		let submissionAction: URL | null = null;
+		let submissionMethod: 'post';
+		let encryptionKey: string | null = null;
+
+		if (submissionElement == null) {
+			submissionAction = null;
+			submissionMethod = 'post';
+			encryptionKey = null;
+		} else {
+			const method = submissionElement.getAttribute('method')?.trim();
+
+			if (method == null || method === 'post' || method === 'form-data-post') {
+				submissionMethod = 'post';
+			} else {
+				throw new Error(`Unexpected <submission method>: ${method}`);
+			}
+
+			const action = submissionElement.getAttribute('action');
+
+			if (action != null) {
+				// TODO: this is known-fallible.
+				submissionAction = new URL(action.trim());
+			}
+
+			encryptionKey = submissionElement.getAttribute('base64RsaPublicKey');
+		}
+
+		this.submissionAction = submissionAction;
+		this.submissionMethod = submissionMethod;
+		this.encryptionKey = encryptionKey;
+	}
+}

package/src/parse/model/ItextTranslation/ItextTranslationDefinition.ts

@@ -0,0 +1,4 @@
+import { StaticDocument } from '../../../integration/xpath/static-dom/StaticDocument.ts';
+import { ItextTranslationRootDefinition } from './ItextTranslationRootDefinition.ts';
+
+export class ItextTranslationDefinition extends StaticDocument<ItextTranslationRootDefinition> {}

package/src/parse/model/ItextTranslation/ItextTranslationRootDefinition.ts

@@ -0,0 +1,42 @@
+import type { XFormsItextTranslationElement } from '@getodk/xpath';
+import { XFORMS_KNOWN_ATTRIBUTE, XFORMS_LOCAL_NAME } from '@getodk/xpath';
+import { StaticElement } from '../../../integration/xpath/static-dom/StaticElement.ts';
+import type { ItextTranslationDefinition } from './ItextTranslationDefinition.ts';
+
+// prettier-ignore
+type ItextTranslationRootKnownAttributeValue<LocalName extends string> =
+	LocalName extends 'lang'
+		? string
+		: string | null;
+
+type AssertItextTranslationRootKnownAttributeValue = <LocalName extends string>(
+	localName: LocalName,
+	value: string | null
+) => asserts value is ItextTranslationRootKnownAttributeValue<LocalName>;
+
+const assertItextTranslationRootKnownAttributeValue: AssertItextTranslationRootKnownAttributeValue =
+	(localName, value) => {
+		if (localName === 'lang' && value == null) {
+			throw new Error('Invalid itext <translation> element: missing `lang` attribute');
+		}
+	};
+
+export class ItextTranslationRootDefinition
+	extends StaticElement<ItextTranslationDefinition>
+	implements XFormsItextTranslationElement<ItextTranslationRootDefinition>
+{
+	override readonly [XFORMS_LOCAL_NAME] = 'translation';
+	override readonly [XFORMS_KNOWN_ATTRIBUTE] = 'lang';
+
+	override getAttributeValue(localName: 'lang'): string;
+	override getAttributeValue(localName: string): string | null;
+	override getAttributeValue<LocalName extends string>(
+		localName: LocalName
+	): ItextTranslationRootKnownAttributeValue<LocalName> {
+		const value = super.getAttributeValue(localName);
+
+		assertItextTranslationRootKnownAttributeValue(localName, value);
+
+		return value;
+	}
+}

package/src/parse/model/ItextTranslation/ItextTranslationsDefinition.ts

@@ -0,0 +1,31 @@
+import type { XFormsItextTranslationMap } from '@getodk/xpath';
+import type { EngineXPathNode } from '../../../integration/xpath/adapter/kind.ts';
+import { parseStaticDocumentFromDOMSubtree } from '../../shared/parseStaticDocumentFromDOMSubtree.ts';
+import type { XFormDOM } from '../../XFormDOM.ts';
+import { ItextTranslationDefinition } from './ItextTranslationDefinition.ts';
+import { ItextTranslationRootDefinition } from './ItextTranslationRootDefinition.ts';
+
+export class ItextTranslationsDefinition
+	extends Map<string, ItextTranslationRootDefinition>
+	implements XFormsItextTranslationMap<EngineXPathNode>
+{
+	static from(xformDOM: XFormDOM): ItextTranslationsDefinition {
+		const translationDefinitions = xformDOM.itextTranslationElements.map((element) => {
+			return parseStaticDocumentFromDOMSubtree(
+				ItextTranslationDefinition,
+				ItextTranslationRootDefinition,
+				element
+			);
+		});
+
+		return new this(translationDefinitions);
+	}
+
+	private constructor(translations: readonly ItextTranslationDefinition[]) {
+		super(
+			translations.map(({ root }) => {
+				return [root.getAttributeValue('lang'), root];
+			})
+		);
+	}
+}

package/src/parse/model/LeafNodeDefinition.ts

@@ -1,15 +1,23 @@
+import type { ValueType } from '../../client/ValueType.ts';
+import {
+	NamespaceDeclarationMap,
+	type NamedSubtreeDefinition,
+} from '../../lib/names/NamespaceDeclarationMap.ts';
+import { QualifiedName } from '../../lib/names/QualifiedName.ts';
 import type { AnyBodyElementDefinition, ControlElementDefinition } from '../body/BodyDefinition.ts';
 import type { BindDefinition } from './BindDefinition.ts';
 import { DescendentNodeDefinition } from './DescendentNodeDefinition.ts';
-import type { NodeDefinition, ParentNodeDefinition } from './NodeDefinition.ts';
+import type { ParentNodeDefinition } from './NodeDefinition.ts';
 
-export class LeafNodeDefinition
+export class LeafNodeDefinition<V extends ValueType = ValueType>
 	extends DescendentNodeDefinition<'leaf-node', ControlElementDefinition | null>
-	implements NodeDefinition<'leaf-node'>
+	implements NamedSubtreeDefinition
 {
 	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;
@@ -26,7 +34,9 @@ export class LeafNodeDefinition
 
 		super(parent, bind, bodyElement);
 
-		this.nodeName = node.localName;
+		this.valueType = bind.type.resolved satisfies ValueType as V;
+		this.qualifiedName = new QualifiedName(node);
+		this.namespaceDeclarations = new NamespaceDeclarationMap(this);
 		this.defaultValue = node.textContent ?? '';
 	}
 

package/src/parse/model/ModelBindMap.ts

@@ -1,6 +1,7 @@
 import type { XFormDefinition } from '../XFormDefinition.ts';
 import { BindDefinition } from './BindDefinition.ts';
 import type { BindElement, BindNodeset } from './BindElement.ts';
+import { DEFAULT_BIND_TYPE } from './BindTypeDefinition.ts';
 import type { ModelDefinition } from './ModelDefinition.ts';
 
 class ArtificialBindElement implements BindElement {
@@ -15,6 +16,10 @@ class ArtificialBindElement implements BindElement {
 			return this.ancestorNodeset;
 		}
 
+		if (name === 'type') {
+			return DEFAULT_BIND_TYPE;
+		}
+
 		return null;
 	}
 
@@ -37,15 +42,8 @@ export class ModelBindMap extends Map<BindNodeset, BindDefinition> {
 		protected readonly form: XFormDefinition,
 		protected readonly model: ModelDefinition
 	) {
-		const bindElements = form.xformDOM.rootEvaluator.evaluateNodes<BindElement & Element>(
-			'./xf:bind[@nodeset]',
-			{
-				contextNode: form.xformDOM.model,
-			}
-		);
-
 		super(
-			bindElements.map((bindElement) => {
+			form.xformDOM.binds.map((bindElement) => {
 				const nodeset = bindElement.getAttribute('nodeset');
 				const bind = new BindDefinition(form, model, nodeset, bindElement);
 

package/src/parse/model/ModelDefinition.ts

@@ -1,14 +1,19 @@
 import type { XFormDefinition } from '../XFormDefinition.ts';
+import { FormSubmissionDefinition } from './FormSubmissionDefinition.ts';
+import { ItextTranslationsDefinition } from './ItextTranslation/ItextTranslationsDefinition.ts';
 import { ModelBindMap } from './ModelBindMap.ts';
 import { RootDefinition } from './RootDefinition.ts';
 
 export class ModelDefinition {
 	readonly binds: ModelBindMap;
 	readonly root: RootDefinition;
+	readonly itextTranslations: ItextTranslationsDefinition;
 
 	constructor(readonly form: XFormDefinition) {
+		const submission = new FormSubmissionDefinition(form.xformDOM);
 		this.binds = ModelBindMap.fromModel(this);
-		this.root = new RootDefinition(form, this, form.body.classes);
+		this.root = new RootDefinition(form, this, submission, form.body.classes);
+		this.itextTranslations = ItextTranslationsDefinition.from(form.xformDOM);
 	}
 
 	toJSON() {

package/src/parse/model/NodeDefinition.ts

@@ -1,3 +1,8 @@
+import type {
+	NamedSubtreeDefinition,
+	NamespaceDeclarationMap,
+} from '../../lib/names/NamespaceDeclarationMap.ts';
+import type { QualifiedName } from '../../lib/names/QualifiedName.ts';
 import type { AnyBodyElementDefinition } from '../body/BodyDefinition.ts';
 import type { RepeatElementDefinition } from '../body/RepeatElementDefinition.ts';
 import type { BindDefinition } from './BindDefinition.ts';
@@ -83,55 +88,28 @@ export type ChildNodeInstanceDefinition =
 	| SubtreeDefinition
 	| LeafNodeDefinition;
 
-// prettier-ignore
-export type NodeChildren<Type extends NodeDefinitionType> =
-	Type extends ParentNodeDefinition['type']
-		? readonly ChildNodeDefinition[]
-		: null;
-
-// prettier-ignore
-export type NodeInstances<Type extends NodeDefinitionType> =
-	Type extends 'repeat-range'
-		? readonly RepeatInstanceDefinition[]
-		: null;
-
-// prettier-ignore
-export type NodeParent<Type extends NodeDefinitionType> =
-	Type extends ChildNodeDefinition['type'] | ChildNodeInstanceDefinition['type']
-		? ParentNodeDefinition
-		: null;
-
-// TODO: leaf-node may be Attr
-// prettier-ignore
-export type ModelNode<Type extends NodeDefinitionType> =
-	Type extends 'repeat-range'
-		? null
-		: Element;
+export abstract class NodeDefinition<Type extends NodeDefinitionType>
+	implements NamedSubtreeDefinition
+{
+	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 children: readonly ChildNodeDefinition[] | null;
+	abstract readonly instances: readonly RepeatInstanceDefinition[] | null;
+	abstract readonly defaultValue: string | null;
+
+	/** @todo leaf-node may be Attr */
+	abstract readonly node: Element | null;
 
-// prettier-ignore
-export type NodeDefaultValue<Type extends NodeDefinitionType> =
-	Type extends 'leaf-node'
-		? string
-		: null;
-
-export interface NodeDefinition<Type extends NodeDefinitionType> {
-	readonly type: Type;
-
-	readonly bind: BindDefinition;
 	readonly nodeset: string;
-	readonly nodeName: string;
-	readonly bodyElement: AnyBodyElementDefinition | RepeatElementDefinition | null;
 
-	readonly isTranslated: boolean;
-	readonly dependencyExpressions: ReadonlySet<string>;
-
-	readonly root: RootDefinition;
-	readonly parent: NodeParent<Type>;
-	readonly children: NodeChildren<Type>;
-	readonly instances: NodeInstances<Type>;
-
-	readonly node: ModelNode<Type>;
-	readonly defaultValue: NodeDefaultValue<Type>;
+	constructor(readonly bind: BindDefinition) {
+		this.nodeset = bind.nodeset;
+	}
 }
 
 export type AnyNodeDefinition =
@@ -142,5 +120,3 @@ export type AnyNodeDefinition =
 	| RepeatInstanceDefinition
 	| SubtreeDefinition
 	| LeafNodeDefinition;
-
-export type TypedNodeDefinition<Type> = Extract<AnyNodeDefinition, { readonly type: Type }>;

package/src/parse/model/NoteNodeDefinition.ts

@@ -1,6 +1,7 @@
 import type { NoteNode } from '../../client/NoteNode.ts';
+import type { ValueType } from '../../client/ValueType.ts';
 import type { AnyBodyElementDefinition } from '../body/BodyDefinition.ts';
-import type { InputDefinition } from '../body/control/InputDefinition.ts';
+import type { InputControlDefinition } from '../body/control/InputControlDefinition.ts';
 import { BindComputationExpression } from '../expression/BindComputationExpression.ts';
 import type { ConstantTruthyDependentExpression } from '../expression/abstract/DependentExpression.ts';
 import type { HintDefinition } from '../text/HintDefinition.ts';
@@ -14,11 +15,11 @@ export type NoteReadonlyDefinition =
 	&	BindComputationExpression<'readonly'>
 	& ConstantTruthyDependentExpression;
 
-export interface NoteBindDefinition extends BindDefinition {
+export interface NoteBindDefinition<V extends ValueType> extends BindDefinition<V> {
 	readonly readonly: NoteReadonlyDefinition;
 }
 
-const isNoteBindDefinition = (bind: BindDefinition): bind is NoteBindDefinition => {
+const isNoteBindDefinition = (bind: BindDefinition): bind is NoteBindDefinition<ValueType> => {
 	return bind.readonly.isConstantTruthyExpression();
 };
 
@@ -31,19 +32,19 @@ export type NoteTextDefinition =
 /**
  * @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
+ * and 'input' 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 class NoteNodeDefinition extends LeafNodeDefinition {
-	static from(
+export class NoteNodeDefinition<V extends ValueType = ValueType> extends LeafNodeDefinition<V> {
+	static from<V extends ValueType>(
 		parent: ParentNodeDefinition,
-		bind: BindDefinition,
+		bind: BindDefinition<V>,
 		bodyElement: AnyBodyElementDefinition | null,
 		node: Element
-	): NoteNodeDefinition | null {
+	): NoteNodeDefinition<V> | null {
 		if (!isNoteBindDefinition(bind) || bodyElement?.type !== 'input') {
 			return null;
 		}
@@ -60,8 +61,8 @@ export class NoteNodeDefinition extends LeafNodeDefinition {
 
 	constructor(
 		parent: ParentNodeDefinition,
-		override readonly bind: NoteBindDefinition,
-		override readonly bodyElement: InputDefinition,
+		override readonly bind: NoteBindDefinition<V>,
+		override readonly bodyElement: InputControlDefinition,
 		readonly noteTextDefinition: NoteTextDefinition,
 		node: Element
 	) {