@getodk/xforms-engine 0.1.0

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@getodk/xforms-engine",
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "description": "XForms engine for ODK Web Forms",
+  "type": "module",
+  "author": "getodk",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/getodk/web-forms",
+    "directory": "packages/xforms-engine"
+  },
+  "bugs": "https://github.com/getodk/web-forms/issues",
+  "homepage": "https://getodk.org/",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "solid": "./dist/solid.js",
+      "import": "./dist/index.js",
+      "browser": "./dist/index.js",
+      "development": "./src/index.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": "^18.19.1 || ^20.11.1",
+    "yarn": "1.22.19"
+  },
+  "scripts": {
+    "build": "npm-run-all -nl build:*",
+    "build:clean": "rimraf dist/",
+    "build:js": "vite build",
+    "build:solid": "export VITE_BUILD_TARGET=solid && vite build",
+    "dev": "vite",
+    "docs": "npm-run-all -nl docs:*",
+    "docs:clean": "rimraf api-docs/",
+    "docs:api": "typedoc --readme none --out api-docs --entryPoints \"src/**/*\"",
+    "docs:serve": "http-server api-docs -o modules/client",
+    "test": "npm-run-all --print-name --print-label test-node:* test-browser:*",
+    "test-node:jsdom": "vitest run",
+    "test-browser:chromium": "BROWSER_NAME=chromium vitest run",
+    "test-browser:firefox": "BROWSER_NAME=firefox vitest run",
+    "test-browser:webkit": "BROWSER_NAME=webkit vitest run",
+    "test-watch:jsdom": "vitest",
+    "test-watch:chromium": "BROWSER_NAME=chromium vitest",
+    "test-watch:firefox": "BROWSER_NAME=firefox vitest",
+    "test-watch:webkit": "BROWSER_NAME=webkit vitest",
+    "test:types": "tsc --project ./tsconfig.json --emitDeclarationOnly false --noEmit"
+  },
+  "dependencies": {
+    "solid-js": "^1.8.3"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.23.2",
+    "@getodk/tree-sitter-xpath": "0.1.0",
+    "@getodk/xpath": "0.1.0",
+    "@playwright/test": "^1.42.1",
+    "@suid/vite-plugin": "^0.1.5",
+    "@vitest/browser": "^1.3.1",
+    "babel-plugin-transform-jsbi-to-bigint": "^1.4.0",
+    "http-server": "^14.1.1",
+    "jsdom": "^24.0.0",
+    "typedoc": "^0.25.12",
+    "unplugin-fonts": "^1.1.1",
+    "vite": "^5.1.5",
+    "vite-plugin-babel": "^1.2.0",
+    "vite-plugin-dts": "^3.7.3",
+    "vite-plugin-no-bundle": "^3.0.0",
+    "vite-plugin-solid": "^2.10.1",
+    "vitest": "^1.3.1",
+    "vitest-github-actions-reporter": "^0.11.1"
+  },
+  "peerDependencies": {
+    "solid-js": "^1.8.3"
+  },
+  "peerDependenciesMeta": {
+    "solid-js": {
+      "optional": true
+    }
+  }
+}

package/src/XFormDOM.ts

@@ -0,0 +1,224 @@
+import { XFORMS_NAMESPACE_URI } from '@getodk/common/constants/xmlns.ts';
+import { XFormsXPathEvaluator } from '@getodk/xpath';
+
+const domParser = new DOMParser();
+
+const openingTag = (element: Element) => element.outerHTML.replace(/>(.|\n)*/, '>');
+
+/**
+ * Per ODK XForms spec:
+ *
+ * > To link a body element with its corresponding data node and binding, both
+ * > `nodeset` and `ref` attributes can be used. The convention that is helpful is
+ * > the one used in XLSForms: use `nodeset="/some/path"` for `<repeat>` and
+ * > `<itemset>` elements and use `ref="/some/path"` for everything else.
+ */
+const normalizeBodyRefNodesetAttributes = (body: Element): void => {
+	const referenceElements = body.querySelectorAll(
+		'itemset[ref], repeat[ref], *[nodeset]:not(itemset, repeat)'
+	);
+
+	for (const element of referenceElements) {
+		switch (element.localName) {
+			case 'itemset':
+			case 'repeat': {
+				// Non-null assertion safe by selector
+				const ref = element.getAttribute('ref')!;
+
+				element.setAttribute('nodeset', ref);
+				element.removeAttribute('ref');
+				break;
+			}
+
+			default: {
+				// Non-null assertion safe by selector
+				const nodeset = element.getAttribute('nodeset')!;
+
+				element.setAttribute('ref', nodeset);
+				element.removeAttribute('nodeset');
+			}
+		}
+	}
+};
+
+const normalizeRepeatGroups = (xformDocument: XMLDocument, body: Element): void => {
+	const repeats = body.querySelectorAll('repeat');
+
+	for (const repeat of repeats) {
+		// Non-null assertion safe because `querySelectorAll` returns descendants
+		const parent = repeat.parentElement!;
+		const repeatNodeset = repeat.getAttribute('nodeset');
+
+		if (repeatNodeset == null) {
+			throw new Error('Found <repeat> without `nodeset` attribute');
+		}
+
+		let group: Element | null = null;
+
+		if (parent.localName === 'group') {
+			const groupRef = parent.getAttribute('ref');
+
+			if (groupRef === repeatNodeset) {
+				group = parent;
+			}
+		}
+
+		if (group == null) {
+			group = xformDocument.createElementNS(XFORMS_NAMESPACE_URI, 'group');
+			group.setAttribute('ref', repeatNodeset);
+			repeat.before(group);
+			group.append(repeat);
+		}
+	}
+};
+
+interface NormalizedXForm {
+	readonly xformDocument: XMLDocument;
+	readonly rootEvaluator: XFormsXPathEvaluator;
+	readonly html: Element;
+	readonly body: Element;
+	readonly normalizedXML: string;
+}
+
+interface XFormDOMNormalizationOptions {
+	readonly isNormalized: boolean;
+}
+
+/**
+ * Performs preprocess operations to normalize certain aspects of an XForm
+ * structure for consistency when building up its runtime representations.
+ * Currently this preprocessing:
+ *
+ * - Ensures consistent use of `ref` and `nodeset` where ambiguous in the
+ *   ODK XForms spec
+ * - Ensures `<repeat>` body elements are always enclosed by a `<group>`
+ *   with the same `ref`
+ */
+const parseNormalizedXForm = (
+	sourceXML: string,
+	options: XFormDOMNormalizationOptions
+): NormalizedXForm => {
+	const xformDocument: XMLDocument = domParser.parseFromString(sourceXML, 'text/xml');
+	const rootEvaluator = new XFormsXPathEvaluator({
+		rootNode: xformDocument,
+	});
+	const html = rootEvaluator.evaluateNonNullElement('/h:html');
+	const body = rootEvaluator.evaluateNonNullElement('./h:body', {
+		contextNode: html,
+	});
+
+	let normalizedXML: string;
+
+	if (options.isNormalized) {
+		normalizedXML = sourceXML;
+	} else {
+		normalizeBodyRefNodesetAttributes(body);
+		normalizeRepeatGroups(xformDocument, body);
+
+		normalizedXML = html.outerHTML;
+	}
+
+	return {
+		xformDocument,
+		rootEvaluator,
+		html,
+		body,
+		normalizedXML,
+	};
+};
+
+export class XFormDOM {
+	static from(sourceXML: string) {
+		return new this(sourceXML, { isNormalized: false });
+	}
+
+	protected readonly normalizedXML: string;
+
+	// XPath
+	readonly rootEvaluator: XFormsXPathEvaluator;
+	readonly primaryInstanceEvaluator: XFormsXPathEvaluator;
+
+	// Commonly accessed landmark nodes
+	readonly xformDocument: XMLDocument;
+
+	readonly html: Element;
+
+	readonly head: Element;
+	readonly title: Element;
+
+	readonly model: Element;
+	readonly primaryInstance: Element;
+	readonly primaryInstanceRoot: Element;
+
+	readonly body: Element;
+
+	protected constructor(
+		protected readonly sourceXML: string,
+		options: XFormDOMNormalizationOptions
+	) {
+		const normalizedXForm: NormalizedXForm = parseNormalizedXForm(sourceXML, options);
+		const { xformDocument, html, body, rootEvaluator, normalizedXML } = normalizedXForm;
+		const head = rootEvaluator.evaluateNonNullElement('./h:head', {
+			contextNode: html,
+		});
+		const title = rootEvaluator.evaluateNonNullElement('./h:title', {
+			contextNode: head,
+		});
+		const model = rootEvaluator.evaluateNonNullElement('./xf:model', {
+			contextNode: head,
+		});
+		// TODO: Evidently primary instance root will not always have an id
+		const primaryInstanceRoot = rootEvaluator.evaluateNonNullElement('./xf:instance/*[@id]', {
+			contextNode: model,
+		});
+		// TODO: invert primary instance/root lookups
+		const primaryInstance = rootEvaluator.evaluateNonNullElement('..', {
+			contextNode: primaryInstanceRoot,
+		});
+
+		this.normalizedXML = normalizedXML;
+		this.rootEvaluator = rootEvaluator;
+		this.primaryInstanceEvaluator = new XFormsXPathEvaluator({
+			rootNode: primaryInstance,
+		});
+		this.xformDocument = xformDocument;
+		this.html = html;
+		this.head = head;
+		this.title = title;
+		this.model = model;
+		this.primaryInstance = primaryInstance;
+		this.primaryInstanceRoot = primaryInstanceRoot;
+		this.body = body;
+	}
+
+	// TODO: anticipating this will be an entry point for edits as well
+	createInstance(): XFormDOM {
+		return new XFormDOM(this.normalizedXML, { isNormalized: true });
+	}
+
+	toJSON() {
+		const {
+			rootEvaluator,
+			primaryInstanceEvaluator,
+			html,
+			head,
+			title,
+			model,
+			primaryInstance,
+			primaryInstanceRoot,
+			xformDocument,
+			...rest
+		} = this;
+
+		return {
+			...rest,
+			xformDocument: '#document',
+			html: openingTag(html),
+			head: openingTag(head),
+			title: openingTag(title),
+			model: openingTag(model),
+			primaryInstance: openingTag(primaryInstance),
+			primaryInstanceRoot: openingTag(primaryInstanceRoot),
+		};
+	}
+}

package/src/XFormDataType.ts

@@ -0,0 +1,64 @@
+import type { CollectionValues } from '@getodk/common/types/collections/CollectionValues.ts';
+
+/**
+ * Like JavaRosa. Presumably for explicit types which aren't impelemnted?
+ */
+const UNSUPPORTED_DATA_TYPE = 'UNSUPPORTED';
+
+export type UnsupportedDataType = typeof UNSUPPORTED_DATA_TYPE;
+
+/**
+ * Like JavaRosa. Presumably for e.g. groups with explicit binds (`relevant` etc)?
+ */
+const NULL_DATA_TYPE = 'NULL';
+
+export type NullDataType = typeof NULL_DATA_TYPE;
+
+/**
+ * As in ODK XForms Spec.
+ *
+ * TODO: it's unclear why JavaRosa's `DataType` hews closely to the spec, but
+ * has certain differences (e.g. string -> TEXT, int -> INTEGER). It's also
+ * not immediately clear how additive types like CHOICE and MULTIPLE_ITEMS
+ * square with the underlying spec types.
+ */
+export const XFORM_SPEC_DATA_TYPES = [
+	'string',
+	'int',
+	'boolean',
+	'decimal',
+	'date',
+	'time',
+	'dateTime',
+	'geopoint',
+	'geotrace',
+	'geoshape',
+	'binary',
+	'barcode',
+	'intent',
+] as const;
+
+const isSupportedDataType = (bindType: string): bindType is XFormSpecDataType =>
+	XFORM_SPEC_DATA_TYPES.includes(bindType as XFormSpecDataType);
+
+export type XFormSpecDataType = CollectionValues<typeof XFORM_SPEC_DATA_TYPES>;
+
+export type XFormDataType = NullDataType | UnsupportedDataType | XFormSpecDataType;
+
+const DEFAULT_XFORM_DATA_TYPE = 'string';
+
+export type DefaultXFormDataType = typeof DEFAULT_XFORM_DATA_TYPE;
+
+// TODO: groups -> NULL?
+// TODO: XSD namespace
+export const bindDataType = (bindType: string | null): XFormDataType => {
+	if (bindType == null) {
+		return DEFAULT_XFORM_DATA_TYPE;
+	}
+
+	if (isSupportedDataType(bindType)) {
+		return bindType;
+	}
+
+	return UNSUPPORTED_DATA_TYPE;
+};

package/src/XFormDefinition.ts

@@ -0,0 +1,40 @@
+import { XFormDOM } from './XFormDOM.ts';
+import { BodyDefinition } from './body/BodyDefinition.ts';
+import { ModelDefinition } from './model/ModelDefinition.ts';
+
+export class XFormDefinition {
+	readonly xformDOM: XFormDOM;
+	readonly xformDocument: XMLDocument;
+
+	readonly id: string;
+	readonly title: string;
+
+	readonly rootReference: string;
+
+	readonly body: BodyDefinition;
+	readonly model: ModelDefinition;
+
+	constructor(readonly sourceXML: string) {
+		const xformDOM = XFormDOM.from(sourceXML);
+
+		this.xformDOM = xformDOM;
+
+		const { primaryInstanceRoot, title, xformDocument } = xformDOM;
+		const id = primaryInstanceRoot.getAttribute('id');
+
+		if (id == null) {
+			throw new Error('Primary instance root has no id');
+		}
+
+		this.xformDocument = xformDocument;
+		this.id = id;
+		this.title = title.textContent ?? '';
+
+		// TODO: highly unlikely primary instance root will need a namespace prefix
+		// but noting it just in case there is such weird usage...
+		this.rootReference = `/${primaryInstanceRoot.localName}`;
+
+		this.body = new BodyDefinition(this);
+		this.model = new ModelDefinition(this);
+	}
+}

package/src/body/BodyDefinition.ts

@@ -0,0 +1,202 @@
+import type { XFormDefinition } from '../XFormDefinition.ts';
+import { DependencyContext } from '../expression/DependencyContext.ts';
+import { UnsupportedBodyElementDefinition } from './UnsupportedBodyElementDefinition.ts';
+import { ControlDefinition } from './control/ControlDefinition.ts';
+import { InputDefinition } from './control/InputDefinition.ts';
+import type { AnySelectDefinition } from './control/select/SelectDefinition.ts';
+import { SelectDefinition } from './control/select/SelectDefinition.ts';
+import { LogicalGroupDefinition } from './group/LogicalGroupDefinition.ts';
+import { PresentationGroupDefinition } from './group/PresentationGroupDefinition.ts';
+import { RepeatGroupDefinition } from './group/RepeatGroupDefinition.ts';
+import { StructuralGroupDefinition } from './group/StructuralGroupDefinition.ts';
+
+export interface BodyElementParentContext {
+	readonly reference: string | null;
+	readonly element: Element;
+}
+
+type SupportedBodyElementDefinition =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| RepeatGroupDefinition
+	| LogicalGroupDefinition
+	| PresentationGroupDefinition
+	| StructuralGroupDefinition
+	| InputDefinition
+	| AnySelectDefinition;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type BodyElementDefinitionConstructor = new (...args: any[]) => SupportedBodyElementDefinition;
+
+const BodyElementDefinitionConstructors = [
+	RepeatGroupDefinition,
+	LogicalGroupDefinition,
+	PresentationGroupDefinition,
+	StructuralGroupDefinition,
+	InputDefinition,
+	SelectDefinition,
+] as const satisfies readonly BodyElementDefinitionConstructor[];
+
+export type AnyBodyElementDefinition =
+	| SupportedBodyElementDefinition
+	| UnsupportedBodyElementDefinition;
+
+export type BodyElementDefinitionArray = readonly AnyBodyElementDefinition[];
+
+export type AnyBodyElementType = AnyBodyElementDefinition['type'];
+
+export type AnyGroupElementDefinition = Extract<
+	AnyBodyElementDefinition,
+	{ readonly type: `${string}-group` }
+>;
+
+export type NonRepeatGroupElementDefinition = Exclude<
+	AnyGroupElementDefinition,
+	{ readonly type: 'repeat-group' }
+>;
+
+const isGroupElementDefinition = (
+	element: AnyBodyElementDefinition
+): element is AnyGroupElementDefinition => {
+	return element.type.endsWith('-group');
+};
+
+export const groupElementDefinition = (
+	element: AnyBodyElementDefinition
+): AnyGroupElementDefinition | null => {
+	return isGroupElementDefinition(element) ? element : null;
+};
+
+export type AnyControlElementDefinition = Extract<
+	AnyBodyElementDefinition,
+	{ readonly category: 'control' }
+>;
+
+const isControlElementDefinition = (
+	element: AnyBodyElementDefinition
+): element is AnyControlElementDefinition => {
+	return element.category === 'control';
+};
+
+export const controlElementDefinition = (
+	element: AnyBodyElementDefinition
+): AnyControlElementDefinition | null => {
+	return isControlElementDefinition(element) ? element : null;
+};
+
+type BodyElementReference = string;
+
+class BodyElementMap extends Map<BodyElementReference, AnyBodyElementDefinition> {
+	constructor(elements: BodyElementDefinitionArray) {
+		super();
+
+		this.mapElementsByReference(elements);
+	}
+
+	protected mapElementsByReference(elements: BodyElementDefinitionArray) {
+		for (const element of elements) {
+			const { reference } = element;
+
+			if (element instanceof RepeatGroupDefinition) {
+				if (reference == null) {
+					throw new Error('Missing reference for repeat/repeat group');
+				}
+
+				this.set(reference, element);
+				this.mapElementsByReference(element.repeatChildren);
+			}
+
+			if (
+				element instanceof LogicalGroupDefinition ||
+				element instanceof PresentationGroupDefinition ||
+				element instanceof StructuralGroupDefinition
+			) {
+				if (reference != null) {
+					this.set(reference, element);
+				}
+
+				this.mapElementsByReference(element.children);
+			}
+
+			if (element instanceof ControlDefinition) {
+				this.set(element.reference, element);
+			}
+		}
+	}
+
+	override set(reference: BodyElementReference, element: AnyBodyElementDefinition) {
+		if (this.has(reference)) {
+			throw new Error(`Multiple body elements for reference: ${reference}`);
+		}
+
+		return super.set(reference, element);
+	}
+
+	getBodyElementType(reference: BodyElementReference): AnyBodyElementType | null {
+		return this.get(reference)?.type ?? null;
+	}
+
+	toJSON() {
+		return Object.fromEntries(this.entries());
+	}
+}
+
+export class BodyDefinition extends DependencyContext {
+	static getChildElementDefinitions(
+		form: XFormDefinition,
+		parent: BodyElementParentContext,
+		parentElement: Element,
+		children: readonly Element[] = Array.from(parentElement.children)
+	): readonly AnyBodyElementDefinition[] {
+		return Array.from(children).map((element) => {
+			const { localName } = element;
+
+			for (const Constructor of BodyElementDefinitionConstructors) {
+				if (Constructor.isCompatible(localName, element)) {
+					return new Constructor(form, parent, element);
+				}
+			}
+
+			return new UnsupportedBodyElementDefinition(form, parent, element);
+		});
+	}
+
+	readonly element: Element;
+	readonly elements: readonly AnyBodyElementDefinition[];
+
+	protected readonly elementsByReference: BodyElementMap;
+
+	// DependencyContext
+	readonly parentReference = null;
+	readonly reference: string;
+
+	constructor(protected readonly form: XFormDefinition) {
+		super();
+
+		const { body: element } = form.xformDOM;
+
+		this.reference = form.rootReference;
+		this.element = element;
+		this.elements = BodyDefinition.getChildElementDefinitions(form, this, element);
+		this.elementsByReference = new BodyElementMap(this.elements);
+	}
+
+	getBodyElement(reference: string): AnyBodyElementDefinition | null {
+		return this.elementsByReference.get(reference) ?? null;
+	}
+
+	getRepeatGroup(reference: string): RepeatGroupDefinition | null {
+		const element = this.getBodyElement(reference);
+
+		if (element?.type === 'repeat-group') {
+			return element;
+		}
+
+		return null;
+	}
+
+	toJSON() {
+		const { form, ...rest } = this;
+
+		return rest;
+	}
+}

package/src/body/BodyElementDefinition.ts

@@ -0,0 +1,62 @@
+import type { XFormDefinition } from '../XFormDefinition.ts';
+import { DependencyContext } from '../expression/DependencyContext.ts';
+import type { BodyElementParentContext } from './BodyDefinition.ts';
+import type { HintDefinition } from './text/HintDefinition.ts';
+import type { LabelDefinition } from './text/LabelDefinition.ts';
+
+/**
+ * These category names roughly correspond to each of the ODK XForms spec's
+ * {@link https://getodk.github.io/xforms-spec/#body-elements | Body Elements}
+ * tables.
+ */
+type BodyElementCategory = 'control' | 'structure' | 'support' | 'UNSUPPORTED';
+
+export abstract class BodyElementDefinition<Type extends string> extends DependencyContext {
+	// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+	// @ts-ignore
+	// eslint-disable-next-line @typescript-eslint/no-unused-vars
+	static isCompatible(localName: string, element: Element): boolean {
+		throw new Error('Must be overridden by BodyElementDefinition subclass');
+	}
+
+	abstract readonly category: BodyElementCategory;
+	abstract readonly type: Type;
+	readonly hint: HintDefinition | null = null;
+	readonly label: LabelDefinition | null = null;
+
+	readonly reference: string | null = null;
+	readonly parentReference: string | null;
+
+	protected constructor(
+		protected readonly form: XFormDefinition,
+		readonly parent: BodyElementParentContext,
+		readonly element: Element
+	) {
+		super();
+		this.parentReference = parent.reference;
+	}
+
+	toJSON(): object {
+		const { form, parent, ...rest } = this;
+
+		return rest;
+	}
+}
+
+type BodyElementDefinitionClass = Pick<
+	typeof BodyElementDefinition,
+	keyof typeof BodyElementDefinition
+>;
+
+// prettier-ignore
+export type BodyElementDefinitionConstructor =
+	& BodyElementDefinitionClass
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	& (new (form: XFormDefinition, element: Element) => BodyElementDefinition<any>);
+
+type BodyElementDefinitionInstance = InstanceType<BodyElementDefinitionConstructor>;
+
+export type TypedBodyElementDefinition<Type extends string> = Extract<
+	BodyElementDefinitionInstance,
+	{ readonly type: Type }
+>;