@getodk/xforms-engine 0.1.0

package/src/body/RepeatDefinition.ts

@@ -0,0 +1,54 @@
+import { JAVAROSA_NAMESPACE_URI } from '@getodk/common/constants/xmlns.ts';
+import type { XFormDefinition } from '../XFormDefinition.ts';
+import type { BodyElementDefinitionArray } from './BodyDefinition.ts';
+import { BodyElementDefinition } from './BodyElementDefinition.ts';
+import type { RepeatGroupDefinition } from './group/RepeatGroupDefinition.ts';
+
+export class RepeatDefinition extends BodyElementDefinition<'repeat'> {
+	override readonly category = 'structure';
+	readonly type = 'repeat';
+	override readonly reference: string;
+
+	// TODO: this will fall into the growing category of non-`BindExpression`
+	// cases which have roughly the same design story.
+	readonly countExpression: string | null;
+
+	readonly isFixedCount: boolean;
+
+	readonly children: BodyElementDefinitionArray;
+
+	constructor(
+		form: XFormDefinition,
+		readonly groupDefinition: RepeatGroupDefinition,
+		element: Element
+	) {
+		super(form, groupDefinition, element);
+
+		const reference = element.getAttribute('nodeset');
+
+		if (reference == null) {
+			throw new Error('Invalid repeat: missing `nodeset` reference');
+		}
+
+		this.reference = reference;
+		this.countExpression = element.getAttributeNS(JAVAROSA_NAMESPACE_URI, 'count');
+		this.children = groupDefinition.getChildren(element);
+
+		// Spec says this can be either `true()` or `false()`. That said, it
+		// could also presumably be `true ( )` or whatever.
+		const noAddRemove =
+			element
+				.getAttributeNS(JAVAROSA_NAMESPACE_URI, 'noAddRemove')
+				?.trim()
+				.replaceAll(/\s+/g, '') ?? 'false()';
+
+		// TODO: **probably** safe to disregard anything else?
+		this.isFixedCount = noAddRemove === 'true()';
+	}
+
+	override toJSON() {
+		const { form, groupDefinition, parent, ...rest } = this;
+
+		return rest;
+	}
+}

package/src/body/UnsupportedBodyElementDefinition.ts

@@ -0,0 +1,17 @@
+import type { XFormDefinition } from '../XFormDefinition.ts';
+import type { BodyElementParentContext } from './BodyDefinition.ts';
+import { BodyElementDefinition } from './BodyElementDefinition.ts';
+
+export class UnsupportedBodyElementDefinition extends BodyElementDefinition<'UNSUPPORTED'> {
+	static override isCompatible(): boolean {
+		return true;
+	}
+
+	override readonly category = 'UNSUPPORTED';
+	readonly type = 'UNSUPPORTED';
+	override readonly reference: null = null;
+
+	constructor(form: XFormDefinition, parent: BodyElementParentContext, element: Element) {
+		super(form, parent, element);
+	}
+}

package/src/body/control/ControlDefinition.ts

@@ -0,0 +1,42 @@
+import type { XFormDefinition } from '../../XFormDefinition.ts';
+import type { BodyElementParentContext } from '../BodyDefinition.ts';
+import { BodyElementDefinition } from '../BodyElementDefinition.ts';
+import { HintDefinition } from '../text/HintDefinition.ts';
+import { LabelDefinition } from '../text/LabelDefinition.ts';
+
+// prettier-ignore
+type ControlType =
+	| 'input'
+	| 'range'
+	| 'rank'
+	| 'select'
+	| 'select1'
+	| 'trigger'
+	| 'upload';
+
+export abstract class ControlDefinition<
+	Type extends ControlType,
+> extends BodyElementDefinition<Type> {
+	override readonly category = 'control';
+	abstract override readonly type: Type;
+	override readonly reference: string;
+	override readonly label: LabelDefinition | null;
+	override readonly hint: HintDefinition | null;
+
+	constructor(form: XFormDefinition, parent: BodyElementParentContext, element: Element) {
+		super(form, parent, element);
+
+		const reference = element.getAttribute('ref');
+
+		if (reference == null) {
+			throw new Error(`Invalid control: missing ref attribute`);
+		}
+
+		this.reference = reference;
+		this.label = LabelDefinition.forControl(form, this);
+		this.hint = HintDefinition.forElement(form, this);
+	}
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyControlDefinition = ControlDefinition<any>;

package/src/body/control/InputDefinition.ts

@@ -0,0 +1,9 @@
+import { ControlDefinition } from './ControlDefinition.ts';
+
+export class InputDefinition extends ControlDefinition<'input'> {
+	static override isCompatible(localName: string): boolean {
+		return localName === 'input';
+	}
+
+	readonly type = 'input';
+}

package/src/body/control/select/ItemDefinition.ts

@@ -0,0 +1,31 @@
+import { getValueElement, type ItemElement } from '../../../lib/dom/query.ts';
+import type { XFormDefinition } from '../../../XFormDefinition.ts';
+import { BodyElementDefinition } from '../../BodyElementDefinition.ts';
+import { LabelDefinition } from '../../text/LabelDefinition.ts';
+import type { AnySelectDefinition } from './SelectDefinition.ts';
+
+export class ItemDefinition extends BodyElementDefinition<'item'> {
+	override readonly category = 'support';
+	override readonly type = 'item';
+
+	override readonly label: LabelDefinition | null;
+	readonly value: string;
+
+	constructor(
+		form: XFormDefinition,
+		override readonly parent: AnySelectDefinition,
+		element: ItemElement
+	) {
+		const valueElement = getValueElement(element);
+		const value = valueElement?.textContent;
+
+		if (value == null) {
+			throw new Error('<item> has no <value>');
+		}
+
+		super(form, parent, element);
+
+		this.label = LabelDefinition.forItem(form, this);
+		this.value = value;
+	}
+}

package/src/body/control/select/ItemsetDefinition.ts

@@ -0,0 +1,36 @@
+import { getValueElement, type ItemsetElement } from '../../../lib/dom/query.ts';
+import type { XFormDefinition } from '../../../XFormDefinition.ts';
+import { BodyElementDefinition } from '../../BodyElementDefinition.ts';
+import { LabelDefinition } from '../../text/LabelDefinition.ts';
+import { ItemsetNodesetExpression } from './ItemsetNodesetExpression.ts';
+import { ItemsetValueExpression } from './ItemsetValueExpression.ts';
+import type { AnySelectDefinition } from './SelectDefinition.ts';
+
+export class ItemsetDefinition extends BodyElementDefinition<'itemset'> {
+	override readonly category = 'support';
+	readonly type = 'itemset';
+
+	override readonly reference: string;
+	override readonly label: LabelDefinition | null;
+
+	readonly nodes: ItemsetNodesetExpression;
+	readonly value: ItemsetValueExpression;
+
+	constructor(form: XFormDefinition, select: AnySelectDefinition, element: ItemsetElement) {
+		const valueElement = getValueElement(element);
+		const valueExpression = valueElement?.getAttribute('ref');
+
+		if (valueExpression == null) {
+			throw new Error(`<itemset> has no <value>`);
+		}
+
+		super(form, select, element);
+
+		const nodesetExpression = element.getAttribute('nodeset');
+
+		this.reference = nodesetExpression;
+		this.nodes = new ItemsetNodesetExpression(this, nodesetExpression);
+		this.value = new ItemsetValueExpression(this, valueExpression);
+		this.label = LabelDefinition.forItemset(form, this);
+	}
+}

package/src/body/control/select/ItemsetNodesetContext.ts

@@ -0,0 +1,26 @@
+import { DependencyContext } from '../../../expression/DependencyContext.ts';
+import type { AnyDependentExpression } from '../../../expression/DependentExpression.ts';
+import type { ItemsetDefinition } from './ItemsetDefinition.ts';
+
+export class ItemsetNodesetContext extends DependencyContext {
+	override readonly parentReference = null;
+	override readonly reference: string;
+
+	constructor(
+		protected readonly itemset: ItemsetDefinition,
+		nodesetExpression: string
+	) {
+		super();
+
+		this.reference = nodesetExpression;
+	}
+
+	override set isTranslated(value: true) {
+		super.isTranslated = value;
+		this.itemset.isTranslated = value;
+	}
+
+	override registerDependentExpression(expression: AnyDependentExpression): void {
+		this.itemset.registerDependentExpression(expression);
+	}
+}

package/src/body/control/select/ItemsetNodesetExpression.ts

@@ -0,0 +1,8 @@
+import { DependentExpression } from '../../../expression/DependentExpression.ts';
+import type { ItemsetDefinition } from './ItemsetDefinition.ts';
+
+export class ItemsetNodesetExpression extends DependentExpression<'nodes'> {
+	constructor(itemset: ItemsetDefinition, nodesetExpression: string) {
+		super(itemset, 'nodes', nodesetExpression);
+	}
+}

package/src/body/control/select/ItemsetValueExpression.ts

@@ -0,0 +1,11 @@
+import { DependentExpression } from '../../../expression/DependentExpression.ts';
+import type { ItemsetDefinition } from './ItemsetDefinition.ts';
+
+export class ItemsetValueExpression extends DependentExpression<'string'> {
+	constructor(
+		readonly itemset: ItemsetDefinition,
+		expression: string
+	) {
+		super(itemset, 'string', expression);
+	}
+}

package/src/body/control/select/SelectDefinition.ts

@@ -0,0 +1,74 @@
+import type { CollectionValues } from '@getodk/common/types/collections/CollectionValues.ts';
+import type { LocalNamedElement } from '@getodk/common/types/dom.ts';
+import type { XFormDefinition } from '../../../XFormDefinition.ts';
+import { getItemElements, getItemsetElement } from '../../../lib/dom/query.ts';
+import type { AnyBodyElementDefinition, BodyElementParentContext } from '../../BodyDefinition.ts';
+import { ControlDefinition } from '../ControlDefinition.ts';
+import { ItemDefinition } from './ItemDefinition.ts';
+import { ItemsetDefinition } from './ItemsetDefinition.ts';
+
+// TODO: `<trigger>` is *almost* reasonable to support here too. The main
+// hesitation is that its single, implicit "item" does not have a distinct
+// <label>, and presumably has different UX **and translation** considerations.
+const selectLocalNames = new Set(['rank', 'select', 'select1'] as const);
+
+export type SelectType = CollectionValues<typeof selectLocalNames>;
+
+export interface SelectElement extends LocalNamedElement<SelectType> {}
+
+const isSelectElement = (
+	element: Element,
+	localName: string = element.localName
+): element is SelectElement => {
+	return selectLocalNames.has(localName as SelectType);
+};
+
+export class SelectDefinition<Type extends SelectType> extends ControlDefinition<Type> {
+	static override isCompatible(localName: string, element: Element): boolean {
+		return isSelectElement(element, localName);
+	}
+
+	static isSelect(element: AnyBodyElementDefinition): element is AnySelectDefinition {
+		return selectLocalNames.has(element.type as SelectType);
+	}
+
+	override readonly type: Type;
+	override readonly element: SelectElement;
+
+	readonly itemset: ItemsetDefinition | null;
+	readonly items: readonly ItemDefinition[];
+
+	constructor(form: XFormDefinition, parent: BodyElementParentContext, element: Element) {
+		if (!isSelectElement(element)) {
+			throw new Error(`Invalid select element: <${element.nodeName}>`);
+		}
+
+		super(form, parent, element);
+
+		this.element = element;
+		this.type = element.localName as Type;
+
+		const itemsetElement = getItemsetElement(element);
+		const itemElements = getItemElements(element);
+
+		if (itemsetElement == null) {
+			this.itemset = null;
+			this.items = itemElements.map((itemElement) => {
+				return new ItemDefinition(form, this, itemElement);
+			});
+		} else {
+			if (itemElements.length > 0) {
+				throw new Error(`<${element.nodeName}> has both <itemset> and <item> children`);
+			}
+
+			this.items = [];
+			this.itemset = new ItemsetDefinition(form, this, itemsetElement);
+		}
+	}
+
+	override toJSON() {
+		return {};
+	}
+}
+
+export type AnySelectDefinition = SelectDefinition<SelectType>;

package/src/body/group/BaseGroupDefinition.ts

@@ -0,0 +1,137 @@
+import { UpsertableMap } from '@getodk/common/lib/collections/UpsertableMap.ts';
+import type { XFormDOM } from '../../XFormDOM.ts';
+import type { XFormDefinition } from '../../XFormDefinition.ts';
+import { getLabelElement, getRepeatElement } from '../../lib/dom/query.ts';
+import {
+	BodyDefinition,
+	type BodyElementDefinitionArray,
+	type BodyElementParentContext,
+} from '../BodyDefinition.ts';
+import { BodyElementDefinition } from '../BodyElementDefinition.ts';
+import { LabelDefinition } from '../text/LabelDefinition.ts';
+
+/**
+ * These type names are derived from **and expand upon** the language used in
+ * the ODK XForms spec to describe various group usage. Whereas the spec
+ * language allows for a group to be described as more than one case, the intent
+ * here is to establish exclusive naming which may or may not compound. As such:
+ *
+ * - `logical-group`, per spec language, is a group with a `ref`; its usage here
+ *   differs from the spec language in that it _may_ have a `<label>` child but
+ *   is not also treated as a `presentation-group` (which is only used for
+ *   groups which do not have a `ref`)
+ * - `presentation-group` is a group with a `<label>` child; its usage here
+ *   differs from the spec language in that `presentation-group` does **not**
+ *   have a `ref`
+ * - `repeat-group` is not mentioned by the spec; it is an extension of
+ *   `logical-group`, wherein its `ref` is the same as its immediate `<repeat>`
+ *   child's `nodeset` (usage of each attribute is normalized during
+ *   initialization, in {@link XFormDOM})
+ * - `structural-group` is any `<group>` element which does not satisfy any of
+ *   the other usage scenarios; this isn't exactly the terminology used, but is
+ *   the most closely fitting name for the concept where the other sceanarios
+ *   do not apply
+ *
+ * A more succinct decision tree:
+ *
+ * - `<group ref="$ref"><repeat nodeset="$ref">` -> `repeat-group`, else
+ * - `<group ref="$ref">` -> `logical-group`, else
+ * - `<group><label>` -> `presentation-group`, else
+ * - `<group>` -> `structural-group`
+ */
+export type GroupType =
+	| 'logical-group'
+	| 'presentation-group'
+	| 'repeat-group'
+	| 'structural-group';
+
+export abstract class BaseGroupDefinition<
+	Type extends GroupType,
+> extends BodyElementDefinition<Type> {
+	private static groupTypes = new UpsertableMap<Element, GroupType | null>();
+
+	protected static getGroupType(localName: string, element: Element): GroupType | null {
+		return this.groupTypes.upsert(element, () => {
+			if (localName !== 'group') {
+				return null;
+			}
+
+			const ref = element.getAttribute('ref');
+
+			if (ref != null) {
+				const repeat = getRepeatElement(element);
+
+				if (repeat == null) {
+					return 'logical-group';
+				}
+
+				if (repeat.getAttribute('nodeset') === ref) {
+					return 'repeat-group';
+				}
+
+				throw new Error('Unexpected <repeat> child of unrelated <group>');
+			}
+
+			const label = getLabelElement(element);
+
+			if (label == null) {
+				return 'structural-group';
+			}
+
+			return 'presentation-group';
+		});
+	}
+
+	override readonly category = 'structure';
+
+	readonly children: BodyElementDefinitionArray;
+
+	override readonly reference: string | null;
+	override readonly label: LabelDefinition | null;
+
+	constructor(
+		form: XFormDefinition,
+		parent: BodyElementParentContext,
+		element: Element,
+		children?: BodyElementDefinitionArray
+	) {
+		super(form, parent, element);
+
+		this.children = children ?? this.getChildren(element);
+		this.reference = element.getAttribute('ref');
+		this.label = LabelDefinition.forGroup(form, this);
+	}
+
+	getChildren(element: Element): BodyElementDefinitionArray {
+		const { form } = this;
+		const children = Array.from(element.children).filter((child) => {
+			const childName = child.localName;
+
+			return childName !== 'label' && childName !== 'repeat';
+		});
+
+		return BodyDefinition.getChildElementDefinitions(form, this, element, children);
+	}
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const repeatGroup = <T extends BaseGroupDefinition<any>>(
+	groupDefinition: T
+): Extract<T, BaseGroupDefinition<'repeat-group'>> | null => {
+	if (groupDefinition.type === 'repeat-group') {
+		return groupDefinition as Extract<T, BaseGroupDefinition<'repeat-group'>>;
+	}
+
+	return null;
+};
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const nonRepeatGroup = <T extends BaseGroupDefinition<any>>(
+	groupDefinition: T
+): Exclude<T, BaseGroupDefinition<'repeat-group'>> | null => {
+	if (groupDefinition.type === 'repeat-group') {
+		return null;
+	}
+
+	return groupDefinition as Exclude<T, BaseGroupDefinition<'repeat-group'>>;
+};

package/src/body/group/LogicalGroupDefinition.ts

@@ -0,0 +1,11 @@
+import { BaseGroupDefinition } from './BaseGroupDefinition.ts';
+
+export class LogicalGroupDefinition extends BaseGroupDefinition<'logical-group'> {
+	static override isCompatible(localName: string, element: Element): boolean {
+		return this.getGroupType(localName, element) === 'logical-group';
+	}
+
+	readonly type = 'logical-group';
+}
+
+export type LogicalGroupDefinitionClass = typeof LogicalGroupDefinition;

package/src/body/group/PresentationGroupDefinition.ts

@@ -0,0 +1,28 @@
+import type { XFormDefinition } from '../../XFormDefinition.ts';
+import type { BodyElementParentContext } from '../BodyDefinition.ts';
+import { LabelDefinition } from '../text/LabelDefinition.ts';
+import { BaseGroupDefinition } from './BaseGroupDefinition.ts';
+
+export class PresentationGroupDefinition extends BaseGroupDefinition<'presentation-group'> {
+	static override isCompatible(localName: string, element: Element): boolean {
+		return this.getGroupType(localName, element) === 'presentation-group';
+	}
+
+	readonly type = 'presentation-group';
+
+	override readonly label: LabelDefinition;
+
+	constructor(form: XFormDefinition, parent: BodyElementParentContext, element: Element) {
+		super(form, parent, element);
+
+		const label = LabelDefinition.forGroup(form, this);
+
+		if (label == null) {
+			throw new Error('Invalid presentation-group: missing label');
+		}
+
+		this.label = label;
+	}
+}
+
+export type PresentationGroupDefinitionClass = typeof PresentationGroupDefinition;

package/src/body/group/RepeatGroupDefinition.ts

@@ -0,0 +1,91 @@
+import { getRepeatElement } from '../../lib/dom/query.ts';
+import type { XFormDefinition } from '../../XFormDefinition.ts';
+import type { BodyElementDefinitionArray, BodyElementParentContext } from '../BodyDefinition.ts';
+import { RepeatDefinition } from '../RepeatDefinition.ts';
+import { BaseGroupDefinition } from './BaseGroupDefinition.ts';
+
+/**
+ * TODO: The `RepeatGroupDefinition`/`RepeatDefinition` types are currently
+ * expected to always pair, mirroring the corresponding XForm structure, e.g.
+ *
+ * ```xml
+ * <group ref="/root/rep"> <!-- RepeatGroupDefinition -->
+ *   <repeat nodeset="/root/rep" /> <!-- RepeatDefinition -->
+ * </group>
+ * ```
+ *
+ * This structure has already been a source of one bug (where a recursive walk
+ * through a `BodyDefinition`'s descendants failed to reach the children of
+ * `RepeatDefinition`s). It seems likely this will continue to be a footgun.
+ * After some discussion with @lognaturel, I concluded that the pairing isn't
+ * strictly necessary, as this should be considered invalid:
+ *
+ * ```xml
+ * <group ref="/root/rep">
+ *   <repeat nodeset="/root/rep" />
+ *   <input ref="/root/rep/not-a-repeat-child" />
+ * </group>
+ * ```
+ *
+ * It **may** make sense to collapse these types in the future, but I've held
+ * off, following another discussion with @lognaturel. There's some potential
+ * for group/repeat labeling ambiguity.
+ *
+ * - The current design accommodates sharing a repeat-containing group's label
+ *   across multiple repeat instances, but
+ * - The
+ *   {@link https://github.com/getodk/xforms-spec/blob/791753a09fabd3d64d8cb95776dc0cef71fa4446/_sections/60-repeats.md?plain=1#L46 | ODK XForms spec suggests}
+ *   a repeat's first group might be a better candidate
+ *
+ * Example of such a structure:
+ *
+ * ```xml
+ * <group ref="/root/foo">
+ *   <label>Foo (outer label)</label>
+ *   <repeat nodeset="/root/foo">
+ *     <group>
+ *       <label>Foo (inner label)</label>
+ *       <!-- ... -->
+ *     </group>
+ *   </repeat>
+ * </group>
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore - All this so I could attach a JSDoc comment to something other
+// than the actual class...
+// eslint-disable-next-line @typescript-eslint/no-empty-interface, @typescript-eslint/no-unused-vars
+interface IgnoreMeIAmJustHereForTheJSDoc {}
+
+export class RepeatGroupDefinition extends BaseGroupDefinition<'repeat-group'> {
+	static override isCompatible(localName: string, element: Element): boolean {
+		return this.getGroupType(localName, element) === 'repeat-group';
+	}
+
+	readonly type = 'repeat-group';
+
+	readonly repeat: RepeatDefinition;
+
+	get repeatChildren(): BodyElementDefinitionArray {
+		return this.repeat.children;
+	}
+
+	constructor(form: XFormDefinition, parent: BodyElementParentContext, element: Element) {
+		// TODO: this has already been queried at least twice before reaching this
+		// point!
+		const repeat = getRepeatElement(element);
+
+		// TODO: and as such, this should not happen
+		if (repeat == null) {
+			throw new Error('Invalid repeat-group');
+		}
+
+		super(form, parent, element);
+
+		const repeatDefinition = new RepeatDefinition(form, this, repeat);
+
+		this.repeat = repeatDefinition;
+	}
+}
+
+export type RepeatGroupDefinitionClass = typeof RepeatGroupDefinition;

package/src/body/group/StructuralGroupDefinition.ts

@@ -0,0 +1,11 @@
+import { BaseGroupDefinition } from './BaseGroupDefinition.ts';
+
+export class StructuralGroupDefinition extends BaseGroupDefinition<'structural-group'> {
+	static override isCompatible(localName: string, element: Element): boolean {
+		return this.getGroupType(localName, element) === 'structural-group';
+	}
+
+	readonly type = 'structural-group';
+}
+
+export type StructuralGroupDefinitionClass = typeof StructuralGroupDefinition;

package/src/body/text/HintDefinition.ts

@@ -0,0 +1,26 @@
+import { getHintElement } from '../../lib/dom/query.ts';
+import type { XFormDefinition } from '../../XFormDefinition.ts';
+import type { AnyControlDefinition } from '../control/ControlDefinition.ts';
+import type { TextElement } from './TextElementDefinition.ts';
+import { TextElementDefinition } from './TextElementDefinition.ts';
+
+export interface HintElement extends TextElement {
+	readonly localName: 'hint';
+}
+
+export class HintDefinition extends TextElementDefinition<'hint'> {
+	static forElement(
+		form: XFormDefinition,
+		definition: AnyControlDefinition
+	): HintDefinition | null {
+		const hintElement = getHintElement(definition.element);
+
+		if (hintElement == null) {
+			return null;
+		}
+
+		return new this(form, definition, hintElement);
+	}
+
+	readonly type = 'hint';
+}