@getodk/xforms-engine 0.1.0

package/src/model/NodeDefinition.ts

@@ -0,0 +1,146 @@
+import type { AnyBodyElementDefinition } from '../body/BodyDefinition.ts';
+import type { RepeatDefinition } from '../body/RepeatDefinition.ts';
+import type { BindDefinition } from './BindDefinition.ts';
+import type { RepeatInstanceDefinition } from './RepeatInstanceDefinition.ts';
+import type { RepeatSequenceDefinition } from './RepeatSequenceDefinition.ts';
+import type { RepeatTemplateDefinition } from './RepeatTemplateDefinition.ts';
+import type { RootDefinition } from './RootDefinition.ts';
+import type { SubtreeDefinition } from './SubtreeDefinition.ts';
+import type { ValueNodeDefinition } from './ValueNodeDefinition.ts';
+
+/**
+ * Corresponds to the model/entry DOM 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 sequence of model/entry DOM subtrees which in turn
+ * corresponds to a <repeat> in the form body definition.
+ */
+export type RepeatSequenceType = 'repeat-sequence';
+
+/**
+ * Corresponds to a template definition for a repeat sequence, 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-sequence' definition.
+ */
+export type RepeatInstanceType = 'repeat-instance';
+
+/**
+ * Corresponds to a model/entry DOM 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:
+ *
+ * - An element with no child elements
+ * - Any attribute corresponding to a bind's `nodeset` expression
+ */
+export type ValueNodeType = 'value-node';
+
+// prettier-ignore
+export type NodeDefinitionType =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| RootNodeType
+	| RepeatSequenceType
+	| RepeatTemplateType
+	| RepeatInstanceType
+	| SubtreeNodeType
+	| ValueNodeType;
+
+// prettier-ignore
+export type ParentNodeDefinition =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| RootDefinition
+	| RepeatTemplateDefinition
+	| RepeatInstanceDefinition
+	| SubtreeDefinition;
+
+// prettier-ignore
+export type ChildNodeDefinition =
+	| RepeatSequenceDefinition
+	| SubtreeDefinition
+	| ValueNodeDefinition;
+
+// prettier-ignore
+export type ChildNodeInstanceDefinition =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| RepeatTemplateDefinition
+	| RepeatInstanceDefinition
+	| SubtreeDefinition
+	| ValueNodeDefinition;
+
+// 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-sequence'
+		? readonly RepeatInstanceDefinition[]
+		: null;
+
+// prettier-ignore
+export type NodeParent<Type extends NodeDefinitionType> =
+	Type extends ChildNodeDefinition['type'] | ChildNodeInstanceDefinition['type']
+		? ParentNodeDefinition
+		: null;
+
+// TODO: value-node may be Attr
+// prettier-ignore
+export type ModelNode<Type extends NodeDefinitionType> =
+	Type extends 'repeat-sequence'
+		? null
+		: Element;
+
+// prettier-ignore
+export type NodeDefaultValue<Type extends NodeDefinitionType> =
+	Type extends 'value-node'
+		? string
+		: null;
+
+export interface NodeDefinition<Type extends NodeDefinitionType> {
+	readonly type: Type;
+
+	readonly bind: BindDefinition;
+	readonly nodeset: string;
+	readonly nodeName: string;
+	readonly bodyElement: AnyBodyElementDefinition | RepeatDefinition | 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>;
+}
+
+export type AnyNodeDefinition =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| RootDefinition
+	| RepeatSequenceDefinition
+	| RepeatTemplateDefinition
+	| RepeatInstanceDefinition
+	| SubtreeDefinition
+	| ValueNodeDefinition;
+
+export type TypedNodeDefinition<Type> = Extract<AnyNodeDefinition, { readonly type: Type }>;

package/src/model/RepeatInstanceDefinition.ts

@@ -0,0 +1,39 @@
+import { RepeatDefinition } from '../body/RepeatDefinition.ts';
+import { DescendentNodeDefinition } from './DescendentNodeDefinition.ts';
+import type { ChildNodeDefinition, NodeDefinition } from './NodeDefinition.ts';
+import type { RepeatSequenceDefinition } from './RepeatSequenceDefinition.ts';
+
+export class RepeatInstanceDefinition
+	extends DescendentNodeDefinition<'repeat-instance', RepeatDefinition>
+	implements NodeDefinition<'repeat-instance'>
+{
+	readonly type = 'repeat-instance';
+
+	readonly nodeName: string;
+	readonly children: readonly ChildNodeDefinition[];
+	readonly instances = null;
+	readonly defaultValue = null;
+
+	constructor(
+		protected readonly sequence: RepeatSequenceDefinition,
+		readonly node: Element
+	) {
+		const {
+			bind,
+			bodyElement: repeatGroupBodyElement,
+			parent: repeatSequenceParent,
+			root,
+		} = sequence;
+
+		super(repeatSequenceParent, bind, repeatGroupBodyElement.repeat);
+
+		this.nodeName = sequence.nodeName;
+		this.children = root.buildSubtree(this);
+	}
+
+	toJSON() {
+		const { bind, bodyElement, parent, root, sequence, ...rest } = this;
+
+		return rest;
+	}
+}

package/src/model/RepeatSequenceDefinition.ts

@@ -0,0 +1,53 @@
+import { RepeatGroupDefinition } from '../body/group/RepeatGroupDefinition.ts';
+import type { BindDefinition } from './BindDefinition.ts';
+import { DescendentNodeDefinition } from './DescendentNodeDefinition.ts';
+import type { NodeDefinition, ParentNodeDefinition } from './NodeDefinition.ts';
+import { RepeatInstanceDefinition } from './RepeatInstanceDefinition.ts';
+import { RepeatTemplateDefinition } from './RepeatTemplateDefinition.ts';
+
+export class RepeatSequenceDefinition
+	extends DescendentNodeDefinition<'repeat-sequence', RepeatGroupDefinition>
+	implements NodeDefinition<'repeat-sequence'>
+{
+	// TODO: if an implicit template is derived from an instance in a form
+	// definition, should its default values (if any) be cleared? Probably!
+	static createTemplateElement(instanceElement: Element): Element {
+		return instanceElement.cloneNode(true) as Element;
+	}
+
+	static createInstanceElement(templateElement: Element): Element {
+		return templateElement.cloneNode(true) as Element;
+	}
+
+	readonly type = 'repeat-sequence';
+
+	readonly template: RepeatTemplateDefinition;
+	readonly children = null;
+	readonly instances: RepeatInstanceDefinition[];
+
+	readonly node = null;
+	readonly nodeName: string;
+	readonly defaultValue = null;
+
+	constructor(
+		parent: ParentNodeDefinition,
+		bind: BindDefinition,
+		bodyElement: RepeatGroupDefinition,
+		modelNodes: readonly [Element, ...Element[]]
+	) {
+		super(parent, bind, bodyElement);
+		const { template, instanceNodes } = RepeatTemplateDefinition.parseModelNodes(this, modelNodes);
+
+		this.template = template;
+		this.nodeName = template.nodeName;
+		this.instances = instanceNodes.map((element) => {
+			return new RepeatInstanceDefinition(this, element);
+		});
+	}
+
+	toJSON() {
+		const { bind, bodyElement: groupDefinition, parent, root, ...rest } = this;
+
+		return rest;
+	}
+}

package/src/model/RepeatTemplateDefinition.ts

@@ -0,0 +1,150 @@
+import { JAVAROSA_NAMESPACE_URI } from '@getodk/common/constants/xmlns.ts';
+import type { RepeatDefinition } from '../body/RepeatDefinition.ts';
+import { BindDefinition } from './BindDefinition.ts';
+import { DescendentNodeDefinition } from './DescendentNodeDefinition.ts';
+import type { ChildNodeDefinition, NodeDefinition } from './NodeDefinition.ts';
+import type { RepeatSequenceDefinition } from './RepeatSequenceDefinition.ts';
+
+const repeatTemplates = new WeakMap<BindDefinition, RepeatTemplateDefinition>();
+
+interface ExplicitRepeatTemplateElement extends Element {
+	getAttributeNS(namespaceURI: typeof JAVAROSA_NAMESPACE_URI, name: 'template'): string;
+	getAttributeNS(namespaceURI: string | null, name: string): string | null;
+
+	hasAttributeNS(namespaceURI: typeof JAVAROSA_NAMESPACE_URI, name: 'template'): true;
+	(namespaceURI: string | null, name: string): boolean;
+}
+
+const isExplicitRepeatTemplateElement = (
+	element: Element
+): element is ExplicitRepeatTemplateElement => {
+	return element.hasAttributeNS(JAVAROSA_NAMESPACE_URI, 'template');
+};
+
+type InstanceNodes = readonly [template: ExplicitRepeatTemplateElement, ...rest: Element[]];
+
+interface LeafNode extends Element {
+	readonly childElementCount: 0;
+}
+
+const isLeafNode = (element: Element): element is LeafNode => {
+	return element.childElementCount === 0;
+};
+
+const clearLeafNodes = <T extends Element>(element: T): T => {
+	if (isLeafNode(element)) {
+		element.textContent = '';
+	} else {
+		for (const child of element.children) {
+			clearLeafNodes(child);
+		}
+	}
+
+	return element;
+};
+
+const getOrCreateTemplateElement = (element: Element): ExplicitRepeatTemplateElement => {
+	if (isExplicitRepeatTemplateElement(element)) {
+		return element;
+	}
+
+	const clone = element.cloneNode(true) as Element;
+	clone.setAttributeNS(JAVAROSA_NAMESPACE_URI, 'template', '');
+
+	return clearLeafNodes(clone as ExplicitRepeatTemplateElement);
+};
+
+// TODO: under what circumstances should a default instance be created, and is
+// this the appropriate place for that?
+const splitInstanceNodes = (modelNodes: readonly [Element, ...Element[]]): InstanceNodes => {
+	const [first, ...rest] = modelNodes;
+	const template = getOrCreateTemplateElement(first);
+
+	if (template === first) {
+		return [template, ...rest];
+	}
+
+	return [template, ...modelNodes];
+};
+
+interface ParsedRepeatNodes {
+	readonly template: RepeatTemplateDefinition;
+	readonly instanceNodes: readonly Element[];
+}
+
+export class RepeatTemplateDefinition
+	extends DescendentNodeDefinition<'repeat-template', RepeatDefinition>
+	implements NodeDefinition<'repeat-template'>
+{
+	static parseModelNodes(
+		sequence: RepeatSequenceDefinition,
+		modelNodes: readonly [Element, ...Element[]]
+	): ParsedRepeatNodes {
+		const { bind } = sequence;
+
+		let template = repeatTemplates.get(bind);
+		let instanceNodes: readonly Element[];
+
+		if (template == null) {
+			const [templateNode, ...rest] = splitInstanceNodes(modelNodes);
+
+			instanceNodes = rest;
+			template = new this(sequence, templateNode);
+		} else {
+			// TODO: this is under the assumption that for any depth > 1, if a
+			// template has already been defined for the given form definition, any
+			// subsequent nodes matching the repeat's nodeset are implicitly default
+			// instances. Is this right?
+			const duplicateTemplate = modelNodes.find((node) =>
+				node.hasAttributeNS(JAVAROSA_NAMESPACE_URI, 'template')
+			);
+
+			if (duplicateTemplate != null) {
+				throw new Error(`Multiple explicit templates defined for ${bind.nodeset}`);
+			}
+
+			instanceNodes = modelNodes;
+		}
+
+		return {
+			template,
+			instanceNodes,
+		};
+	}
+
+	readonly type = 'repeat-template';
+
+	readonly node: Element;
+	readonly nodeName: string;
+	readonly children: readonly ChildNodeDefinition[];
+	readonly instances = null;
+	readonly defaultValue = null;
+
+	protected constructor(
+		protected readonly sequence: RepeatSequenceDefinition,
+		protected readonly templateNode: ExplicitRepeatTemplateElement
+	) {
+		const {
+			bind,
+			bodyElement: repeatGroupBodyElement,
+			parent: repeatSequenceParent,
+			root,
+		} = sequence;
+
+		super(repeatSequenceParent, bind, repeatGroupBodyElement.repeat);
+
+		const node = templateNode.cloneNode(true) as Element;
+
+		node.removeAttributeNS(JAVAROSA_NAMESPACE_URI, 'template');
+
+		this.node = node;
+		this.nodeName = node.localName;
+		this.children = root.buildSubtree(this);
+	}
+
+	toJSON() {
+		const { bind, bodyElement, parent, root, sequence, ...rest } = this;
+
+		return rest;
+	}
+}

package/src/model/RootDefinition.ts

@@ -0,0 +1,121 @@
+import type { XFormDefinition } from '../XFormDefinition.ts';
+import type { RepeatGroupDefinition } from '../body/group/RepeatGroupDefinition.ts';
+import type { BindDefinition } from './BindDefinition.ts';
+import type { ModelDefinition } from './ModelDefinition.ts';
+import type {
+	ChildNodeDefinition,
+	NodeDefinition,
+	ParentNodeDefinition,
+} from './NodeDefinition.ts';
+import { RepeatSequenceDefinition } from './RepeatSequenceDefinition.ts';
+import { SubtreeDefinition } from './SubtreeDefinition.ts';
+import { ValueNodeDefinition } from './ValueNodeDefinition.ts';
+
+export class RootDefinition implements NodeDefinition<'root'> {
+	readonly type = 'root';
+	readonly bind: BindDefinition;
+	readonly nodeset: string;
+	readonly nodeName: string;
+	readonly bodyElement = null;
+	readonly root = this;
+	readonly parent = null;
+	readonly children: readonly ChildNodeDefinition[];
+	readonly instances = null;
+	readonly node: Element;
+	readonly defaultValue = null;
+
+	readonly isTranslated = false;
+	readonly dependencyExpressions: ReadonlySet<string> = new Set<string>();
+
+	constructor(
+		protected readonly form: XFormDefinition,
+		protected readonly model: ModelDefinition
+	) {
+		// TODO: theoretically the pertinent step in the bind's `nodeset` *could* be
+		// namespaced. It also may make more sense to determine the root nodeset
+		// earlier (i.e. in the appropriate definition class).
+		//
+		// TODO: while it's unlikely a form actually defines a <bind> for the root,
+		// if it did, bind nodesets are not yet normalized, so `/root` may currently
+		// be defined as `/ root` (or even `/ *` or any other valid expression
+		// resolving to the root).
+		const { primaryInstanceRoot } = form.xformDOM;
+		const { localName: rootNodeName } = primaryInstanceRoot;
+
+		this.nodeName = rootNodeName;
+
+		const nodeset = `/${rootNodeName}`;
+		const bind = model.binds.get(nodeset);
+
+		if (bind == null) {
+			throw new Error('Missing root node bind definition');
+		}
+
+		this.bind = bind;
+		this.nodeset = nodeset;
+		this.node = primaryInstanceRoot;
+		this.children = this.buildSubtree(this);
+	}
+
+	buildSubtree(parent: ParentNodeDefinition): readonly ChildNodeDefinition[] {
+		const { form, model } = this;
+		const { body } = form;
+		const { binds } = model;
+		const { bind: parentBind, node } = parent;
+		const { nodeset: parentNodeset } = parentBind;
+
+		const childrenByName = new Map<string, [Element, ...Element[]]>();
+
+		for (const child of node.children) {
+			const { localName } = child;
+
+			let elements = childrenByName.get(localName);
+
+			if (elements == null) {
+				elements = [child];
+				childrenByName.set(localName, elements);
+			} else {
+				// TODO: check if previous element exists, was it previous element
+				// sibling. Highly likely this should otherwise fail!
+				elements.push(child);
+			}
+		}
+
+		return Array.from(childrenByName).map(([localName, children]) => {
+			const nodeset = `${parentNodeset}/${localName}`;
+			const bind = binds.getOrCreateBindDefinition(nodeset);
+			const bodyElement = body.getBodyElement(nodeset);
+			const [firstChild, ...restChildren] = children;
+			const repeatGroup = body.getRepeatGroup(nodeset);
+
+			if (repeatGroup != null) {
+				const repeatDefinition = (bodyElement as RepeatGroupDefinition).repeat;
+
+				if (repeatDefinition == null) {
+					throw 'TODO: this is why I have hesitated to pick an "is repeat" predicate direction';
+				}
+
+				return new RepeatSequenceDefinition(parent, bind, repeatGroup, children);
+			}
+
+			if (restChildren.length) {
+				throw new Error(`Unexpected: multiple elements for non-repeat nodeset: ${nodeset}`);
+			}
+
+			const element = firstChild;
+			const isLeafNode = element.childElementCount === 0;
+
+			if (isLeafNode) {
+				return new ValueNodeDefinition(parent, bind, bodyElement, element);
+			}
+
+			return new SubtreeDefinition(parent, bind, bodyElement, element);
+		});
+	}
+
+	toJSON() {
+		const { bind, bodyElement, form, model, root, ...rest } = this;
+
+		return rest;
+	}
+}

package/src/model/SubtreeDefinition.ts

@@ -0,0 +1,50 @@
+import type {
+	AnyBodyElementDefinition,
+	NonRepeatGroupElementDefinition,
+} from '../body/BodyDefinition.ts';
+import type { BindDefinition } from './BindDefinition.ts';
+import { DescendentNodeDefinition } from './DescendentNodeDefinition.ts';
+import type {
+	ChildNodeDefinition,
+	NodeDefinition,
+	ParentNodeDefinition,
+} from './NodeDefinition.ts';
+
+export class SubtreeDefinition
+	extends DescendentNodeDefinition<'subtree', NonRepeatGroupElementDefinition | null>
+	implements NodeDefinition<'subtree'>
+{
+	readonly type = 'subtree';
+
+	readonly nodeName: string;
+	readonly children: readonly ChildNodeDefinition[];
+	readonly instances = null;
+	readonly defaultValue = null;
+
+	constructor(
+		parent: ParentNodeDefinition,
+		bind: BindDefinition,
+		bodyElement: AnyBodyElementDefinition | null,
+		readonly node: Element
+	) {
+		if (
+			bodyElement != null &&
+			(bodyElement.category !== 'structure' || bodyElement.type === 'repeat-group')
+		) {
+			throw new Error(`Unexpected body element for nodeset ${bind.nodeset}`);
+		}
+
+		super(parent, bind, bodyElement);
+
+		const { root } = parent;
+
+		this.nodeName = node.localName;
+		this.children = root.buildSubtree(this);
+	}
+
+	toJSON() {
+		const { parent, bodyElement, bind, root, ...rest } = this;
+
+		return rest;
+	}
+}

package/src/model/ValueNodeDefinition.ts

@@ -0,0 +1,39 @@
+import type { AnyBodyElementDefinition } from '../body/BodyDefinition.ts';
+import type { AnyControlDefinition } from '../body/control/ControlDefinition.ts';
+import type { BindDefinition } from './BindDefinition.ts';
+import { DescendentNodeDefinition } from './DescendentNodeDefinition.ts';
+import type { NodeDefinition, ParentNodeDefinition } from './NodeDefinition.ts';
+
+export class ValueNodeDefinition
+	extends DescendentNodeDefinition<'value-node', AnyControlDefinition | null>
+	implements NodeDefinition<'value-node'>
+{
+	readonly type = 'value-node';
+
+	readonly nodeName: string;
+	readonly children = null;
+	readonly instances = null;
+	readonly defaultValue: string;
+
+	constructor(
+		parent: ParentNodeDefinition,
+		bind: BindDefinition,
+		bodyElement: AnyBodyElementDefinition | null,
+		readonly node: Element
+	) {
+		if (bodyElement != null && bodyElement.category !== 'control') {
+			throw new Error(`Unexpected body element for nodeset ${bind.nodeset}`);
+		}
+
+		super(parent, bind, bodyElement);
+
+		this.nodeName = node.localName;
+		this.defaultValue = node.textContent ?? '';
+	}
+
+	toJSON() {
+		const { bind, bodyElement, parent, root, ...rest } = this;
+
+		return rest;
+	}
+}