@getodk/xforms-engine 0.2.0 → 0.3.0

package/src/parse/text/ItemLabelDefinition.ts

@@ -0,0 +1,25 @@
+import type { LocalNamedElement } from '@getodk/common/types/dom.ts';
+import type { XFormDefinition } from '../../XFormDefinition.ts';
+import type { ItemDefinition } from '../../body/control/select/ItemDefinition.ts';
+import { getLabelElement } from '../../lib/dom/query.ts';
+import { TextElementDefinition } from './abstract/TextElementDefinition.ts';
+
+interface LabelElement extends LocalNamedElement<'label'> {}
+
+export class ItemLabelDefinition extends TextElementDefinition<'item-label'> {
+	static from(form: XFormDefinition, owner: ItemDefinition): ItemLabelDefinition | null {
+		const labelElement = getLabelElement(owner.element);
+
+		if (labelElement == null) {
+			return null;
+		}
+
+		return new this(form, owner, labelElement);
+	}
+
+	readonly role = 'item-label';
+
+	private constructor(form: XFormDefinition, owner: ItemDefinition, element: LabelElement) {
+		super(form, owner, element);
+	}
+}

package/src/parse/text/ItemsetLabelDefinition.ts

@@ -0,0 +1,44 @@
+import type { LocalNamedElement } from '@getodk/common/types/dom.ts';
+import type { XFormDefinition } from '../../XFormDefinition.ts';
+import type { ItemDefinition } from '../../body/control/select/ItemDefinition.ts';
+import type { ItemsetDefinition } from '../../body/control/select/ItemsetDefinition.ts';
+import { getLabelElement } from '../../lib/dom/query.ts';
+import { ReferenceChunkDefinition } from './ReferenceChunkDefinition.ts';
+import { TranslationChunkDefinition } from './TranslationChunkDefinition.ts';
+import type { RefAttributeChunk } from './abstract/TextElementDefinition.ts';
+import { TextRangeDefinition } from './abstract/TextRangeDefinition.ts';
+
+export type ItemLabelOwner = ItemDefinition | ItemsetDefinition;
+
+interface LabelElement extends LocalNamedElement<'label'> {}
+
+export class ItemsetLabelDefinition extends TextRangeDefinition<'item-label'> {
+	static from(form: XFormDefinition, owner: ItemsetDefinition): ItemsetLabelDefinition | null {
+		const labelElement = getLabelElement(owner.element);
+
+		if (labelElement == null) {
+			return null;
+		}
+
+		return new this(form, owner, labelElement);
+	}
+
+	readonly role = 'item-label';
+	readonly chunks: readonly [RefAttributeChunk];
+
+	private constructor(form: XFormDefinition, owner: ItemsetDefinition, element: LabelElement) {
+		super(form, owner, element);
+
+		const refExpression = element.getAttribute('ref');
+
+		if (refExpression == null) {
+			throw new Error('<itemset><label> missing ref attribute');
+		}
+
+		const refChunk =
+			TranslationChunkDefinition.from(this, refExpression) ??
+			ReferenceChunkDefinition.from(this, refExpression);
+
+		this.chunks = [refChunk];
+	}
+}

package/src/parse/text/LabelDefinition.ts

@@ -0,0 +1,61 @@
+import type { LocalNamedElement } from '@getodk/common/types/dom.ts';
+import type { XFormDefinition } from '../../XFormDefinition.ts';
+import type { AnyGroupElementDefinition } from '../../body/BodyDefinition.ts';
+import type { RepeatElementDefinition } from '../../body/RepeatElementDefinition.ts';
+import type { AnyControlDefinition } from '../../body/control/ControlDefinition.ts';
+import type { BaseGroupDefinition } from '../../body/group/BaseGroupDefinition.ts';
+import { getLabelElement, getRepeatGroupLabelElement } from '../../lib/dom/query.ts';
+import { TextElementDefinition } from './abstract/TextElementDefinition.ts';
+
+// prettier-ignore
+export type LabelOwner =
+	| AnyControlDefinition
+	| AnyGroupElementDefinition
+	| RepeatElementDefinition;
+
+interface LabelElement extends LocalNamedElement<'label'> {}
+
+export class LabelDefinition extends TextElementDefinition<'label'> {
+	static forControl(form: XFormDefinition, control: AnyControlDefinition): LabelDefinition | null {
+		const labelElement = getLabelElement(control.element);
+
+		if (labelElement == null) {
+			return null;
+		}
+
+		return new this(form, control, labelElement);
+	}
+
+	static forRepeatGroup(
+		form: XFormDefinition,
+		repeat: RepeatElementDefinition
+	): LabelDefinition | null {
+		const repeatGroupLabel = getRepeatGroupLabelElement(repeat.element);
+
+		if (repeatGroupLabel == null) {
+			return null;
+		}
+
+		return new this(form, repeat, repeatGroupLabel);
+	}
+
+	static forGroup(
+		form: XFormDefinition,
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		group: BaseGroupDefinition<any>
+	): LabelDefinition | null {
+		const labelElement = getLabelElement(group.element);
+
+		if (labelElement == null) {
+			return null;
+		}
+
+		return new this(form, group, labelElement);
+	}
+
+	readonly role = 'label';
+
+	private constructor(form: XFormDefinition, owner: LabelOwner, element: LabelElement) {
+		super(form, owner, element);
+	}
+}

package/src/parse/text/MessageDefinition.ts

@@ -0,0 +1,49 @@
+import { JAVAROSA_NAMESPACE_URI } from '@getodk/common/constants/xmlns.ts';
+import type { BindDefinition } from '../../model/BindDefinition.ts';
+import { StaticTextChunkDefinition } from './StaticTextChunkDefinition.ts';
+import { TranslationChunkDefinition } from './TranslationChunkDefinition.ts';
+import type { TextBindAttributeLocalName, TextSourceNode } from './abstract/TextRangeDefinition.ts';
+import { TextRangeDefinition } from './abstract/TextRangeDefinition.ts';
+
+export type MessageSourceNode = TextSourceNode<TextBindAttributeLocalName>;
+
+// prettier-ignore
+type MessageChunk =
+	| StaticTextChunkDefinition
+	| TranslationChunkDefinition;
+
+export class MessageDefinition<
+	Type extends TextBindAttributeLocalName,
+> extends TextRangeDefinition<Type> {
+	static from<Type extends TextBindAttributeLocalName>(
+		bind: BindDefinition,
+		type: Type
+	): MessageDefinition<Type> | null {
+		const message = bind.bindElement.getAttributeNS(JAVAROSA_NAMESPACE_URI, type);
+
+		if (message == null) {
+			return null;
+		}
+
+		return new this(bind, type, message);
+	}
+
+	readonly chunks: readonly [MessageChunk];
+
+	private constructor(
+		bind: BindDefinition,
+		readonly role: Type,
+		message: string
+	) {
+		super(bind.form, bind, null);
+
+		const chunk: MessageChunk =
+			TranslationChunkDefinition.fromMessage(this, message) ??
+			StaticTextChunkDefinition.from(this, message);
+
+		this.chunks = [chunk];
+	}
+}
+
+// prettier-ignore
+export type AnyMessageDefinition = MessageDefinition<TextBindAttributeLocalName>;

package/src/parse/text/OutputChunkDefinition.ts

@@ -0,0 +1,25 @@
+import type { KnownAttributeLocalNamedElement } from '@getodk/common/types/dom.ts';
+import { TextChunkDefinition } from './abstract/TextChunkDefinition.ts';
+import type { AnyTextRangeDefinition } from './abstract/TextRangeDefinition.ts';
+
+interface OutputElement extends KnownAttributeLocalNamedElement<'output', 'value'> {}
+
+const isOutputElement = (element: Element): element is OutputElement => {
+	return element.localName === 'output' && element.hasAttribute('value');
+};
+
+export class OutputChunkDefinition extends TextChunkDefinition<'output'> {
+	static from(context: AnyTextRangeDefinition, element: Element): OutputChunkDefinition | null {
+		if (isOutputElement(element)) {
+			return new this(context, element);
+		}
+
+		return null;
+	}
+
+	readonly source = 'output';
+
+	private constructor(context: AnyTextRangeDefinition, element: OutputElement) {
+		super(context, element.getAttribute('value'));
+	}
+}

package/src/parse/text/ReferenceChunkDefinition.ts

@@ -0,0 +1,14 @@
+import { TextChunkDefinition } from './abstract/TextChunkDefinition.ts';
+import type { AnyTextRangeDefinition } from './abstract/TextRangeDefinition.ts';
+
+export class ReferenceChunkDefinition extends TextChunkDefinition<'reference'> {
+	static from(context: AnyTextRangeDefinition, refExpression: string): ReferenceChunkDefinition {
+		return new this(context, refExpression);
+	}
+
+	readonly source = 'reference';
+
+	private constructor(context: AnyTextRangeDefinition, refExpression: string) {
+		super(context, refExpression);
+	}
+}

package/src/parse/text/StaticTextChunkDefinition.ts

@@ -0,0 +1,19 @@
+import { TextChunkDefinition } from './abstract/TextChunkDefinition.ts';
+import type { AnyTextRangeDefinition } from './abstract/TextRangeDefinition.ts';
+
+export type StaticTextChunkSourceNode = Attr | Text;
+
+export class StaticTextChunkDefinition extends TextChunkDefinition<'static'> {
+	static from(context: AnyTextRangeDefinition, stringValue: string): StaticTextChunkDefinition {
+		return new this(context, stringValue);
+	}
+
+	readonly source = 'static';
+
+	private constructor(
+		context: AnyTextRangeDefinition,
+		override readonly stringValue: string
+	) {
+		super(context, 'null');
+	}
+}

package/src/parse/text/TranslationChunkDefinition.ts

@@ -0,0 +1,38 @@
+import { expressionParser } from '@getodk/xpath/expressionParser.js';
+import type { TranslationExpression } from '../xpath/semantic-analysis.ts';
+import { isTranslationExpression } from '../xpath/semantic-analysis.ts';
+import { TextChunkDefinition } from './abstract/TextChunkDefinition.ts';
+import type { AnyTextRangeDefinition } from './abstract/TextRangeDefinition.ts';
+
+export class TranslationChunkDefinition extends TextChunkDefinition<'translation'> {
+	static fromMessage(
+		context: AnyTextRangeDefinition,
+		maybeExpression: string
+	): TranslationChunkDefinition | null {
+		try {
+			expressionParser.parse(maybeExpression);
+		} catch {
+			return null;
+		}
+
+		if (isTranslationExpression(maybeExpression)) {
+			return new this(context, maybeExpression);
+		}
+
+		return null;
+	}
+
+	static from(context: AnyTextRangeDefinition, maybeExpression: string) {
+		if (isTranslationExpression(maybeExpression)) {
+			return new this(context, maybeExpression);
+		}
+
+		return null;
+	}
+
+	readonly source = 'translation';
+
+	private constructor(context: AnyTextRangeDefinition, expression: TranslationExpression) {
+		super(context, expression, { isTranslated: true });
+	}
+}

package/src/parse/text/abstract/TextChunkDefinition.ts

@@ -0,0 +1,38 @@
+import type { TextChunkSource } from '../../../client/TextRange.ts';
+import { DependentExpression } from '../../../expression/DependentExpression.ts';
+import type { OutputChunkDefinition } from '../OutputChunkDefinition.ts';
+import type { ReferenceChunkDefinition } from '../ReferenceChunkDefinition.ts';
+import type { StaticTextChunkDefinition } from '../StaticTextChunkDefinition.ts';
+import type { TranslationChunkDefinition } from '../TranslationChunkDefinition.ts';
+import type { AnyTextRangeDefinition } from './TextRangeDefinition.ts';
+
+interface TextChunkDefinitionOptions {
+	readonly isTranslated?: true;
+}
+
+export abstract class TextChunkDefinition<
+	Source extends TextChunkSource,
+> extends DependentExpression<'string'> {
+	abstract readonly source: Source;
+	readonly stringValue?: string;
+
+	constructor(
+		context: AnyTextRangeDefinition,
+		expression: string,
+		options: TextChunkDefinitionOptions = {}
+	) {
+		super(context, 'string', expression, {
+			semanticDependencies: {
+				translations: options.isTranslated,
+			},
+			ignoreContextReference: true,
+		});
+	}
+}
+
+// prettier-ignore
+export type AnyTextChunkDefinition =
+	| OutputChunkDefinition
+	| ReferenceChunkDefinition
+	| StaticTextChunkDefinition
+	| TranslationChunkDefinition;

package/src/parse/text/abstract/TextElementDefinition.ts

@@ -0,0 +1,71 @@
+import { isElementNode, isTextNode } from '@getodk/common/lib/dom/predicates.ts';
+import type { XFormDefinition } from '../../../XFormDefinition.ts';
+import type { ItemDefinition } from '../../../body/control/select/ItemDefinition.ts';
+import type { ElementTextRole } from '../../../client/TextRange.ts';
+import { parseNodesetReference } from '../../xpath/reference-parsing.ts';
+import type { HintDefinition } from '../HintDefinition.ts';
+import type { ItemLabelDefinition } from '../ItemLabelDefinition.ts';
+import type { ItemsetLabelDefinition } from '../ItemsetLabelDefinition.ts';
+import type { LabelDefinition, LabelOwner } from '../LabelDefinition.ts';
+import { OutputChunkDefinition } from '../OutputChunkDefinition.ts';
+import { ReferenceChunkDefinition } from '../ReferenceChunkDefinition.ts';
+import { StaticTextChunkDefinition } from '../StaticTextChunkDefinition.ts';
+import { TranslationChunkDefinition } from '../TranslationChunkDefinition.ts';
+import type { TextSourceNode } from './TextRangeDefinition.ts';
+import { TextRangeDefinition } from './TextRangeDefinition.ts';
+
+// prettier-ignore
+export type RefAttributeChunk =
+	| ReferenceChunkDefinition
+	| TranslationChunkDefinition;
+
+// prettier-ignore
+type TextElementChildChunk =
+	| OutputChunkDefinition
+	| StaticTextChunkDefinition;
+
+// prettier-ignore
+type TextElementChunks =
+	| readonly [RefAttributeChunk]
+	| readonly TextElementChildChunk[];
+
+type TextElementOwner = ItemDefinition | LabelOwner;
+
+export abstract class TextElementDefinition<
+	Role extends ElementTextRole,
+> extends TextRangeDefinition<Role> {
+	readonly chunks: TextElementChunks;
+
+	constructor(form: XFormDefinition, owner: TextElementOwner, sourceNode: TextSourceNode<Role>) {
+		super(form, owner, sourceNode);
+
+		const context = this as AnyTextElementDefinition;
+		const refExpression = parseNodesetReference(owner, sourceNode, 'ref');
+
+		if (refExpression == null) {
+			this.chunks = Array.from(sourceNode.childNodes).flatMap((childNode) => {
+				if (isElementNode(childNode)) {
+					return OutputChunkDefinition.from(context, childNode) ?? [];
+				}
+
+				if (isTextNode(childNode)) {
+					return StaticTextChunkDefinition.from(context, childNode.data);
+				}
+
+				return [];
+			});
+		} else {
+			const refChunk =
+				TranslationChunkDefinition.from(context, refExpression) ??
+				ReferenceChunkDefinition.from(context, refExpression);
+			this.chunks = [refChunk];
+		}
+	}
+}
+
+// prettier-ignore
+export type AnyTextElementDefinition =
+	| HintDefinition
+	| ItemLabelDefinition
+	| ItemsetLabelDefinition
+	| LabelDefinition;

package/src/parse/text/abstract/TextRangeDefinition.ts

@@ -0,0 +1,70 @@
+import type { LocalNamedElement } from '@getodk/common/types/dom.ts';
+import type { XFormDefinition } from '../../../XFormDefinition.ts';
+import type { TextRole } from '../../../client/TextRange.ts';
+import { DependencyContext } from '../../../expression/DependencyContext.ts';
+import type { AnyDependentExpression } from '../../../expression/DependentExpression.ts';
+import type { AnyMessageDefinition } from '../MessageDefinition.ts';
+import type { AnyTextChunkDefinition } from './TextChunkDefinition.ts';
+import type { AnyTextElementDefinition } from './TextElementDefinition.ts';
+
+export type TextBindAttributeLocalName = 'constraintMsg' | 'requiredMsg';
+export type TextBodyElementLocalName = 'hint' | 'label';
+
+interface TextSourceNodes {
+	readonly constraintMsg: null;
+	readonly hint: LocalNamedElement<'hint'>;
+	readonly label: LocalNamedElement<'label'>;
+	readonly 'item-label': LocalNamedElement<'label'>;
+	readonly requiredMsg: null;
+}
+
+export type TextSourceNode<Type extends TextRole> = TextSourceNodes[Type];
+
+export abstract class TextRangeDefinition<Role extends TextRole> extends DependencyContext {
+	abstract readonly role: Role;
+	readonly parentReference: string | null;
+	readonly reference: string | null;
+
+	abstract readonly chunks: readonly AnyTextChunkDefinition[];
+
+	override get isTranslated(): boolean {
+		return (
+			this.ownerContext.isTranslated || this.chunks.some((chunk) => chunk.source === 'translation')
+		);
+	}
+
+	override set isTranslated(value: true) {
+		if (this.ownerContext != null) {
+			this.ownerContext.isTranslated = value;
+		}
+
+		super.isTranslated = value;
+	}
+
+	protected constructor(
+		readonly form: XFormDefinition,
+		readonly ownerContext: DependencyContext,
+		readonly sourceNode: TextSourceNode<Role>
+	) {
+		super();
+
+		this.reference = ownerContext.reference;
+		this.parentReference = ownerContext.parentReference;
+	}
+
+	override registerDependentExpression(expression: AnyDependentExpression): void {
+		this.ownerContext.registerDependentExpression(expression);
+		super.registerDependentExpression(expression);
+	}
+
+	toJSON(): object {
+		const { form, ownerContext, ...rest } = this;
+
+		return rest;
+	}
+}
+
+// prettier-ignore
+export type AnyTextRangeDefinition =
+	| AnyMessageDefinition
+	| AnyTextElementDefinition;

package/src/parse/xpath/dependency-analysis.ts

@@ -0,0 +1,105 @@
+import { expressionParser } from '@getodk/xpath/expressionParser.js';
+import {
+	resolvePath,
+	resolvePredicateReference,
+	serializeNodesetReference,
+} from './path-resolution.ts';
+import { findPredicateReferences } from './predicate-analysis.ts';
+import type { PathExpressionNode } from './semantic-analysis.ts';
+import { findLocationPathSubExpressionNodes, getPathExpressionNode } from './semantic-analysis.ts';
+
+export interface PathResolutionOptions {
+	/**
+	 * Excludes direct references to the nodeset specified as a context. This flag
+	 * has earlier precedent as `ignoreContextReference` in similar internal APIs.
+	 * The intent, in part, is to allow for certain in-spec exceptions to cycle
+	 * analysis (which we previously did explicitly, and foresee reintroducing in
+	 * some form relatively soon). As such, the default for this flag should be
+	 * overridden when a computation is (A) not among the core `<bind>`
+	 * computations or (B) is a computation which is explicitly expected to have
+	 * self-references (such as `constraint`).
+	 *
+	 * @default false
+	 *
+	 * @todo It is highly likely we will eliminate this in the future. We
+	 * considered removing its precursor (and existing code now referencing this)
+	 * in {@link https://github.com/getodk/web-forms/pull/67}, but ran into issues
+	 * with some of the reactive logic introduced there. It's likely that
+	 * subsequent improvements have addressed those issues, but it's also likely
+	 * that we will want similar special casing when we reintroduce explicit graph
+	 * cycle analysis.
+	 */
+	readonly ignoreReferenceToContextPath?: boolean;
+}
+
+const defaultPathResolutionOptions: Required<PathResolutionOptions> = {
+	ignoreReferenceToContextPath: false,
+};
+
+/**
+ * Resolves XPath paths referenced by an arbitrary expression to XForms
+ * `nodeset` references:
+ *
+ * 1. The provided {@link expression} is analyzed to find path sub-expressions
+ *    (LocationPaths, sub-expressions with a node-set producing FilterExpr).
+ *
+ * 2. When a {@link contextNodeset} is available, each sub-expression is
+ *    resolved to that context. See {@link resolvePath} for additional
+ *    detail.
+ *
+ * 3. Once resolved, each dependency path is further analyzed to identify
+ *    sub-expressions in any of its predicates, resolving each to their
+ *    respective predicates' Steps. See {@link resolvePredicateReference} for
+ *    additional detail.
+ */
+export const resolveDependencyNodesets = (
+	contextNodeset: string | null,
+	expression: string,
+	options: PathResolutionOptions = {}
+): readonly string[] => {
+	const { ignoreReferenceToContextPath } = {
+		...defaultPathResolutionOptions,
+		...options,
+	};
+
+	let contextNode: PathExpressionNode | null = null;
+
+	if (contextNodeset != null) {
+		contextNode = getPathExpressionNode(contextNodeset);
+	}
+
+	const expressionRootNode = expressionParser.parse(expression).rootNode;
+	const subExpressions = findLocationPathSubExpressionNodes(expressionRootNode);
+
+	const resolvedPathLists = subExpressions.flatMap((subExpression) => {
+		const pathNodes = resolvePath(contextNode, subExpression);
+		const predicateReferences = findPredicateReferences(pathNodes);
+		const resolvedPredicateReferences = predicateReferences.map((reference) => {
+			return resolvePredicateReference(
+				contextNode,
+				reference.stepContextNodes,
+				reference.predicatePathNode
+			);
+		});
+
+		return [pathNodes, ...resolvedPredicateReferences];
+	});
+
+	const serializedPaths = Array.from(
+		new Set(
+			resolvedPathLists.map((resolvedPathList) => {
+				return serializeNodesetReference(resolvedPathList, {
+					stripPredicates: true,
+				});
+			})
+		)
+	);
+
+	if (ignoreReferenceToContextPath) {
+		return serializedPaths.filter((result) => {
+			return result !== contextNodeset;
+		});
+	}
+
+	return serializedPaths;
+};