@getodk/xforms-engine 0.5.0 → 0.7.0

package/src/parse/model/BindPreloadDefinition.ts

@@ -0,0 +1,100 @@
+import { JAVAROSA_NAMESPACE_URI } from '@getodk/common/constants/xmlns.ts';
+import type { PartiallyKnownString } from '@getodk/common/types/string/PartiallyKnownString.ts';
+import type { BindElement } from './BindElement.ts';
+
+type PartiallyKnownPreloadParameter<Known extends string> =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	PartiallyKnownString<NonNullable<Known>> | Extract<Known, null>;
+
+interface PreloadParametersByType {
+	readonly uid: string | null;
+	readonly date: PartiallyKnownPreloadParameter<'today'>;
+	readonly timestamp: PartiallyKnownPreloadParameter<'end' | 'start'>;
+
+	readonly property: PartiallyKnownPreloadParameter<
+		// prettier-ignore
+		'deviceid' | 'email' | 'phonenumber' | 'username'
+	>;
+}
+
+type PreloadType = PartiallyKnownString<keyof PreloadParametersByType>;
+
+// prettier-ignore
+type PreloadParameter<Type extends PreloadType> =
+	Type extends keyof PreloadParametersByType
+		? PreloadParametersByType[Type]
+		: string | null;
+
+interface PreloadInput<Type extends PreloadType> {
+	readonly type: Type;
+	readonly parameter: PreloadParameter<Type>;
+}
+
+type AnyPreloadInput = {
+	[Type in PreloadType]: PreloadInput<Type>;
+}[PreloadType];
+
+const getPreloadInput = (bindElement: BindElement): AnyPreloadInput | null => {
+	const type = bindElement.getAttributeNS(JAVAROSA_NAMESPACE_URI, 'preload');
+
+	if (type == null) {
+		return null;
+	}
+
+	const parameter: PreloadParameter<typeof type> = bindElement.getAttributeNS(
+		JAVAROSA_NAMESPACE_URI,
+		'preloadParams'
+	);
+
+	return {
+		type,
+		parameter,
+	};
+};
+
+/**
+ * Parsed representation of
+ * {@link https://getodk.github.io/xforms-spec/#preload-attributes | Preload Attributes}.
+ * If specified on a
+ * {@link https://getodk.github.io/xforms-spec/#bindings | binding}, this will
+ * be parsed to define:
+ *
+ * - {@link type}, a `jr:preload`
+ * - {@link parameter}, an associated `jr:preloadParams` value
+ *
+ * @todo It would probably make sense for the _definition_ to also convey:
+ *
+ * 1. Which {@link https://getodk.github.io/xforms-spec/#events | event} the
+ *    preload is semantically associated with (noting that the spec may be a tad
+ *    overzealous about this association).
+ *
+ * 2. The constant XPath expression (or other computation?) expressed by the
+ *    combined {@link type} and {@link parameter}.
+ */
+export class BindPreloadDefinition<Type extends PreloadType> implements PreloadInput<Type> {
+	static from(bindElement: BindElement): AnyBindPreloadDefinition | null {
+		const input = getPreloadInput(bindElement);
+
+		if (input == null) {
+			return null;
+		}
+
+		return new this(input);
+	}
+
+	readonly type: Type;
+	readonly parameter: PreloadParameter<Type>;
+
+	private constructor(input: PreloadInput<Type>) {
+		this.type = input.type;
+		this.parameter = input.parameter;
+	}
+}
+
+// prettier-ignore
+export type AnyBindPreloadDefinition =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| BindPreloadDefinition<'uid'>
+	| BindPreloadDefinition<'timestamp'>
+	| BindPreloadDefinition<'property'>
+	| BindPreloadDefinition<string>;

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,32 +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 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;
 		}
 	}
 }
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type AnyDescendantNodeDefinition = DescendentNodeDefinition<any, any>;

package/src/parse/model/ItextTranslationsDefinition.ts

@@ -0,0 +1,79 @@
+import type {
+	XFORMS_KNOWN_ATTRIBUTE,
+	XFORMS_LOCAL_NAME,
+	XFormsItextTranslationMap,
+} from '@getodk/xpath';
+import { StaticDocument } from '../../integration/xpath/static-dom/StaticDocument.ts';
+import type { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
+import type { XFormDOM } from '../XFormDOM.ts';
+import { parseStaticDocumentFromDOMSubtree } from '../shared/parseStaticDocumentFromDOMSubtree.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;
+}
+
+type ItextTranslationsDefinitionEntry = readonly [
+	key: string,
+	value: ItextTranslationRootDefinition,
+];
+
+type AssertItextTranslationsDefinitionEntry = (
+	entry: readonly [key: string | null, value: StaticElement]
+) => asserts entry is ItextTranslationsDefinitionEntry;
+
+const assertItextTranslationsDefinitionEntry: AssertItextTranslationsDefinitionEntry = ([
+	key,
+	root,
+]) => {
+	if (key == null || root.qualifiedName.localName !== 'translation') {
+		throw new Error();
+	}
+};
+
+/**
+ * @todo At time of writing, this shouldn't have any observable
+ * consequence—apart from preventing the potential mistake of using an
+ * {@link ItextTranslationDefinition} where an
+ * **instance**-as-{@link StaticDocument} would be expected (i.e. anything
+ * expecting an instance's {@link StaticDocument.nodeset} to be '/', or an its
+ * descendant elements' {@link StaticElement.nodeset} to start with '/'). The
+ * main intent, however, is to leave a breadcrumb back to ideas discussed in
+ * {@link https://github.com/getodk/web-forms/issues/22#issuecomment-2669228571 | Allow output in translation text (#22)}.
+ */
+const itextTranslationNodesetPrefix = (lang: string) => {
+	return `wf:translation('${lang}')`;
+};
+
+export class ItextTranslationsDefinition
+	extends Map<string, ItextTranslationRootDefinition>
+	implements XFormsItextTranslationMap<ItextTranslationRootDefinition>
+{
+	static from(xformDOM: XFormDOM): ItextTranslationsDefinition {
+		const entries = xformDOM.itextTranslationElements.map((element) => {
+			const lang = element.getAttribute('lang');
+			const { root } = parseStaticDocumentFromDOMSubtree(element, {
+				nodesetPrefix: itextTranslationNodesetPrefix(lang),
+			});
+			const entry = [lang, root] as const;
+
+			assertItextTranslationsDefinitionEntry(entry);
+
+			return entry;
+		});
+
+		return new this(entries);
+	}
+
+	private constructor(entries: readonly ItextTranslationsDefinitionEntry[]) {
+		super(entries);
+	}
+}

package/src/parse/model/LeafNodeDefinition.ts

@@ -1,26 +1,31 @@
 import type { ValueType } from '../../client/ValueType.ts';
+import type { StaticLeafElement } from '../../integration/xpath/static-dom/StaticElement.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<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;
 
 	constructor(
 		parent: ParentNodeDefinition,
 		bind: BindDefinition,
 		bodyElement: AnyBodyElementDefinition | null,
-		readonly node: Element
+		readonly template: StaticLeafElement
 	) {
 		if (bodyElement != null && bodyElement.category !== 'control') {
 			throw new Error(`Unexpected body element for nodeset ${bind.nodeset}`);
@@ -29,8 +34,8 @@ export class LeafNodeDefinition<V extends ValueType = ValueType>
 		super(parent, bind, bodyElement);
 
 		this.valueType = bind.type.resolved satisfies ValueType as V;
-		this.nodeName = node.localName;
-		this.defaultValue = node.textContent ?? '';
+		this.qualifiedName = template.qualifiedName;
+		this.namespaceDeclarations = new NamespaceDeclarationMap(this);
 	}
 
 	toJSON() {

package/src/parse/model/ModelDefinition.ts

@@ -1,21 +1,54 @@
+import { ErrorProductionDesignPendingError } from '../../error/ErrorProductionDesignPendingError.ts';
+import type { StaticDocument } from '../../integration/xpath/static-dom/StaticDocument.ts';
+import { parseStaticDocumentFromDOMSubtree } from '../shared/parseStaticDocumentFromDOMSubtree.ts';
 import type { XFormDefinition } from '../XFormDefinition.ts';
-import { FormSubmissionDefinition } from './FormSubmissionDefinition.ts';
-import { ItextTranslationsDefinition } from './ItextTranslation/ItextTranslationsDefinition.ts';
+import { ItextTranslationsDefinition } from './ItextTranslationsDefinition.ts';
 import { ModelBindMap } from './ModelBindMap.ts';
+import type { AnyNodeDefinition } from './NodeDefinition.ts';
+import type { NodeDefinitionMap } from './nodeDefinitionMap.ts';
+import { nodeDefinitionMap } from './nodeDefinitionMap.ts';
 import { RootDefinition } from './RootDefinition.ts';
+import { SubmissionDefinition } from './SubmissionDefinition.ts';
 
 export class ModelDefinition {
 	readonly binds: ModelBindMap;
 	readonly root: RootDefinition;
+	readonly nodes: NodeDefinitionMap;
+	readonly instance: StaticDocument;
 	readonly itextTranslations: ItextTranslationsDefinition;
 
 	constructor(readonly form: XFormDefinition) {
-		const submission = new FormSubmissionDefinition(form.xformDOM);
+		const submission = new SubmissionDefinition(form.xformDOM);
+
 		this.binds = ModelBindMap.fromModel(this);
+		this.instance = parseStaticDocumentFromDOMSubtree(form.xformDOM.primaryInstanceRoot, {
+			nodesetPrefix: '/',
+		});
 		this.root = new RootDefinition(form, this, submission, form.body.classes);
+		this.nodes = nodeDefinitionMap(this.root);
 		this.itextTranslations = ItextTranslationsDefinition.from(form.xformDOM);
 	}
 
+	getNodeDefinition(nodeset: string): AnyNodeDefinition {
+		const definition = this.nodes.get(nodeset);
+
+		if (definition == null) {
+			throw new ErrorProductionDesignPendingError(`No definition for nodeset: ${nodeset}`);
+		}
+
+		return definition;
+	}
+
+	getRootDefinition(instance: StaticDocument): RootDefinition {
+		const definition = this.getNodeDefinition(instance.root.nodeset);
+
+		if (definition !== this.root) {
+			throw new ErrorProductionDesignPendingError();
+		}
+
+		return definition;
+	}
+
 	toJSON() {
 		const { form, ...rest } = this;
 

package/src/parse/model/NodeDefinition.ts

@@ -1,15 +1,19 @@
+import type { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
+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';
 import type { LeafNodeDefinition } from './LeafNodeDefinition.ts';
-import type { RepeatInstanceDefinition } from './RepeatInstanceDefinition.ts';
-import type { AnyRepeatRangeDefinition } from './RepeatRangeDefinition.ts';
-import type { RepeatTemplateDefinition } from './RepeatTemplateDefinition.ts';
+import type { AnyRepeatDefinition } from './RepeatDefinition.ts';
 import type { RootDefinition } from './RootDefinition.ts';
 import type { 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]/*`
@@ -17,34 +21,25 @@ import type { SubtreeDefinition } from './SubtreeDefinition.ts';
 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
@@ -55,9 +50,7 @@ export type LeafNodeType = 'leaf-node';
 export type NodeDefinitionType =
 	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
 	| RootNodeType
-	| RepeatRangeType
-	| RepeatTemplateType
-	| RepeatInstanceType
+	| RepeatType
 	| SubtreeNodeType
 	| LeafNodeType;
 
@@ -65,79 +58,39 @@ export type NodeDefinitionType =
 export type ParentNodeDefinition =
 	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
 	| RootDefinition
-	| RepeatTemplateDefinition
-	| RepeatInstanceDefinition
+	| AnyRepeatDefinition
 	| SubtreeDefinition;
 
 // prettier-ignore
 export type ChildNodeDefinition =
-	| AnyRepeatRangeDefinition
+	| AnyRepeatDefinition
 	| LeafNodeDefinition
 	| SubtreeDefinition;
 
-// prettier-ignore
-export type ChildNodeInstanceDefinition =
-	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
-	| RepeatTemplateDefinition
-	| RepeatInstanceDefinition
-	| 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;
+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 template: StaticElement;
+	abstract readonly children: readonly ChildNodeDefinition[] | 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;
-
-// 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 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;
+	}
 }
 
+// prettier-ignore
 export type AnyNodeDefinition =
 	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
 	| RootDefinition
-	| AnyRepeatRangeDefinition
-	| RepeatTemplateDefinition
-	| RepeatInstanceDefinition
+	| AnyRepeatDefinition
 	| SubtreeDefinition
 	| LeafNodeDefinition;
-
-export type TypedNodeDefinition<Type> = Extract<AnyNodeDefinition, { readonly type: Type }>;

package/src/parse/model/NoteNodeDefinition.ts

@@ -1,4 +1,6 @@
 import type { NoteNode } from '../../client/NoteNode.ts';
+import type { ValueType } from '../../client/ValueType.ts';
+import type { StaticLeafElement } from '../../integration/xpath/static-dom/StaticElement.ts';
 import type { AnyBodyElementDefinition } from '../body/BodyDefinition.ts';
 import type { InputControlDefinition } from '../body/control/InputControlDefinition.ts';
 import { BindComputationExpression } from '../expression/BindComputationExpression.ts';
@@ -14,11 +16,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();
 };
 
@@ -37,13 +39,13 @@ export type NoteTextDefinition =
  * 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 {
+		node: StaticLeafElement
+	): NoteNodeDefinition<V> | null {
 		if (!isNoteBindDefinition(bind) || bodyElement?.type !== 'input') {
 			return null;
 		}
@@ -60,11 +62,11 @@ export class NoteNodeDefinition extends LeafNodeDefinition {
 
 	constructor(
 		parent: ParentNodeDefinition,
-		override readonly bind: NoteBindDefinition,
+		override readonly bind: NoteBindDefinition<V>,
 		override readonly bodyElement: InputControlDefinition,
 		readonly noteTextDefinition: NoteTextDefinition,
-		node: Element
+		template: StaticLeafElement
 	) {
-		super(parent, bind, bodyElement, node);
+		super(parent, bind, bodyElement, template);
 	}
 }