@getodk/xforms-engine 0.3.0 → 0.5.0

package/src/lib/reactivity/node-state/createSpecifiedState.ts

@@ -80,7 +80,7 @@ export type ComputedPropertySpec<T> = Accessor<T>;
 /**
  * @see {@link StaticPropertySpec}
  */
-// eslint-disable-next-line @typescript-eslint/ban-types, @typescript-eslint/no-explicit-any
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type, @typescript-eslint/no-explicit-any
 type NonStaticValue = Function | Signal<any> | SimpleAtomicState<any>;
 
 /**

package/src/lib/reactivity/text/createFieldHint.ts

@@ -1,7 +1,7 @@
 import { type Accessor } from 'solid-js';
 import type { TextRange } from '../../../client/TextRange.ts';
 import type { EvaluationContext } from '../../../instance/internal-api/EvaluationContext.ts';
-import type { LeafNodeDefinition } from '../../../model/LeafNodeDefinition.ts';
+import type { LeafNodeDefinition } from '../../../parse/model/LeafNodeDefinition.ts';
 import { createTextRange } from './createTextRange.ts';
 
 export const createFieldHint = (

package/src/lib/reactivity/text/createNodeLabel.ts

@@ -1,7 +1,7 @@
 import { type Accessor } from 'solid-js';
 import type { TextRange } from '../../../client/TextRange.ts';
 import type { EvaluationContext } from '../../../instance/internal-api/EvaluationContext.ts';
-import type { AnyNodeDefinition } from '../../../model/NodeDefinition.ts';
+import type { AnyNodeDefinition } from '../../../parse/model/NodeDefinition.ts';
 import { createTextRange } from './createTextRange.ts';
 
 export const createNodeLabel = (

package/src/lib/reactivity/text/createNoteText.ts

@@ -2,7 +2,7 @@ import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
 import type { Accessor } from 'solid-js';
 import type { TextRange } from '../../../client/TextRange.ts';
 import type { EvaluationContext } from '../../../instance/internal-api/EvaluationContext.ts';
-import type { NoteTextDefinition } from '../../../parse/NoteNodeDefinition.ts';
+import type { NoteTextDefinition } from '../../../parse/model/NoteNodeDefinition.ts';
 import { createTextRange } from './createTextRange.ts';
 
 // eslint-disable-next-line @typescript-eslint/sort-type-constituents

package/src/lib/reactivity/text/createTextRange.ts

@@ -4,7 +4,7 @@ import type { TextChunkSource, TextRole } from '../../../client/TextRange.ts';
 import type { EvaluationContext } from '../../../instance/internal-api/EvaluationContext.ts';
 import { TextChunk } from '../../../instance/text/TextChunk.ts';
 import { TextRange } from '../../../instance/text/TextRange.ts';
-import type { AnyTextChunkDefinition } from '../../../parse/text/abstract/TextChunkDefinition.ts';
+import type { AnyTextChunkExpression } from '../../../parse/expression/abstract/TextChunkExpression.ts';
 import type { TextRangeDefinition } from '../../../parse/text/abstract/TextRangeDefinition.ts';
 import { createComputedExpression } from '../createComputedExpression.ts';
 
@@ -15,11 +15,11 @@ interface TextChunkComputation {
 
 const createComputedTextChunk = (
 	context: EvaluationContext,
-	textSource: AnyTextChunkDefinition
+	textSource: AnyTextChunkExpression
 ): TextChunkComputation => {
 	const { source } = textSource;
 
-	if (source === 'static') {
+	if (source === 'literal') {
 		const { stringValue } = textSource;
 
 		return {
@@ -29,7 +29,9 @@ const createComputedTextChunk = (
 	}
 
 	return context.scope.runTask(() => {
-		const getText = createComputedExpression(context, textSource);
+		const getText = createComputedExpression(context, textSource, {
+			defaultValue: '',
+		});
 
 		return {
 			source,
@@ -40,17 +42,16 @@ const createComputedTextChunk = (
 
 const createTextChunks = (
 	context: EvaluationContext,
-	textSources: readonly AnyTextChunkDefinition[]
+	textSources: readonly AnyTextChunkExpression[]
 ): Accessor<readonly TextChunk[]> => {
 	return context.scope.runTask(() => {
-		const { root } = context;
 		const chunkComputations = textSources.map((textSource) => {
 			return createComputedTextChunk(context, textSource);
 		});
 
 		return createMemo(() => {
 			return chunkComputations.map(({ source, getText }) => {
-				return new TextChunk(root, source, getText());
+				return new TextChunk(context, source, getText());
 			});
 		});
 	});

package/src/lib/reactivity/validation/createAggregatedViolations.ts

@@ -4,10 +4,11 @@ import type {
 	AncestorNodeValidationState,
 	DescendantNodeViolationReference,
 } from '../../../client/validation.ts';
-import type { AnyParentNode, AnyValueNode } from '../../../instance/hierarchy.ts';
+import type { AnyParentNode } from '../../../instance/hierarchy.ts';
+import type { ValidationContext } from '../../../instance/internal-api/ValidationContext.ts';
 import { createSharedNodeState } from '../node-state/createSharedNodeState.ts';
 
-const violationReference = (node: AnyValueNode): DescendantNodeViolationReference | null => {
+const violationReference = (node: ValidationContext): DescendantNodeViolationReference | null => {
 	const violation = node.getViolation();
 
 	if (violation == null) {
@@ -31,9 +32,13 @@ const collectViolationReferences = (
 	return context.getChildren().flatMap((child) => {
 		switch (child.nodeType) {
 			case 'model-value':
+			case 'input':
 			case 'note':
-			case 'string':
-			case 'select': {
+			case 'select':
+			case 'range':
+			case 'rank':
+			case 'trigger':
+			case 'upload': {
 				const reference = violationReference(child);
 
 				if (reference == null) {

package/src/lib/reactivity/validation/createValidation.ts

@@ -33,7 +33,7 @@ const engineViolationMessage = <Role extends ValidationTextRole>(
 	role: Role
 ): Accessor<EngineViolationMessage<Role>> => {
 	const messageText = VALIDATION_TEXT[role];
-	const chunk = new TextChunk(context.root, 'static', messageText);
+	const chunk = new TextChunk(context, 'literal', messageText);
 	const message = new TextRange('engine', role, [chunk]);
 
 	return () => message;
@@ -75,9 +75,8 @@ const createConstraintValidation = (
 		}
 
 		const isValid = createComputedExpression(context, constraint, {
-			arbitraryDependencies: [context],
+			defaultValue: true,
 		});
-
 		const message = createViolationMessage(context, 'constraintMsg', constraintMsg);
 
 		return createMemo(() => {

package/src/lib/xml-serialization.ts

@@ -0,0 +1,96 @@
+declare const ESCAPED_XML_TEXT_BRAND: unique symbol;
+
+export type EscapedXMLText = string & { readonly [ESCAPED_XML_TEXT_BRAND]: true };
+
+const ATTR_REGEX = /[&<>"]/;
+const CONTENT_REGEX = /[&<>]/;
+
+/**
+ * This is based on the `escapeHTML` implementation in
+ * {@link https://github.com/ryansolid/dom-expressions} (Solid's JSX transform).
+ *
+ * @see {@link https://github.com/ryansolid/dom-expressions/pull/27} for
+ * motivation to derive this implementation approach.
+ *
+ * The intent is that this can be updated easily if the base implementation
+ * changes. As such, some aspects of this implementation differ from some of our
+ * typical code style preferences.
+ *
+ * Notable changes from the base implementation:
+ *
+ * - Formatting: automated only.
+ * - Naming: the {@link text} parameter is named `html` in the base
+ *   implementation. That would be confusing if preserved.
+ * - Types:
+ *     - Parameter types are added (of course)
+ *     - Return type is branded as {@link EscapedXMLText}, to allow downstream
+ *       checks that escaping has been performed. Return statements are cast
+ *       accordingly.
+ *     - {@link text} attempts to minimize risk of double-escaping by excluding
+ *       that same branded type.
+ * - The '>' character is also escaped, necessary for producing valid XML.
+ *
+ * As with the base implementation, we leave some characters unescaped:
+ *
+ * - " (double quote): except when {@link attr} is `true`.
+ *
+ * - ' (single quote): on the assumption that attributes are always serialized
+ *   in double quotes. If we ever move this to `@getodk/common`, we'd want to
+ *   reconsider this assumption.
+ */
+export const escapeXMLText = <Text extends string>(
+	text: Exclude<Text, EscapedXMLText>,
+	attr?: boolean
+): EscapedXMLText => {
+	const match = (attr ? ATTR_REGEX : CONTENT_REGEX).exec(text);
+	if (!match) return text as string as EscapedXMLText;
+	let index = 0;
+	let lastIndex = 0;
+	let out = '';
+	let escape = '';
+	for (index = match.index; index < text.length; index++) {
+		switch (text.charCodeAt(index)) {
+			case 34: // "
+				if (!attr) continue;
+				escape = '&quot;';
+				break;
+			case 38: // &
+				escape = '&amp;';
+				break;
+			case 60: // <
+				escape = '&lt;';
+				break;
+			case 62: // >
+				escape = '&gt;';
+				break;
+			default:
+				continue;
+		}
+		if (lastIndex !== index) out += text.substring(lastIndex, index);
+		lastIndex = index + 1;
+		out += escape;
+	}
+	return lastIndex !== index
+		? ((out + text.substring(lastIndex, index)) as EscapedXMLText)
+		: (out as EscapedXMLText);
+};
+
+const serializeElementXML = (nodeName: string, children: string): string => {
+	if (children === '') {
+		return `<${nodeName}/>`;
+	}
+
+	// TODO: attributes
+	return `<${nodeName}>${children}</${nodeName}>`;
+};
+
+export const serializeParentElementXML = (
+	nodeName: string,
+	serializedChildren: readonly string[]
+): string => {
+	return serializeElementXML(nodeName, serializedChildren.join(''));
+};
+
+export const serializeLeafElementXML = (nodeName: string, xmlValue: EscapedXMLText): string => {
+	return serializeElementXML(nodeName, xmlValue.normalize());
+};

package/src/{XFormDOM.ts → parse/XFormDOM.ts}

@@ -1,5 +1,37 @@
 import { XFORMS_NAMESPACE_URI, XMLNS_NAMESPACE_URI } from '@getodk/common/constants/xmlns.ts';
-import { XFormsXPathEvaluator } from '@getodk/xpath';
+import type {
+	KnownAttributeLocalNamedElement,
+	LocalNamedElement,
+} from '@getodk/common/types/dom.ts';
+import { DefaultEvaluator } from '@getodk/xpath';
+
+interface DOMBindElement extends KnownAttributeLocalNamedElement<'bind', 'nodeset'> {}
+
+export interface DOMItextTranslationElement
+	extends KnownAttributeLocalNamedElement<'translation', 'lang'> {}
+
+interface DOMInstanceElement extends LocalNamedElement<'instance'> {}
+
+export interface DOMSecondaryInstanceElement
+	extends KnownAttributeLocalNamedElement<'instance', 'id'> {}
+
+type AssertDOMSecondaryInstanceElement = (
+	element: DOMInstanceElement
+) => asserts element is DOMSecondaryInstanceElement;
+
+const assertDOMSecondaryInstanceElement: AssertDOMSecondaryInstanceElement = (element) => {
+	if (!element.hasAttribute('id')) {
+		throw new Error('Invalid secondary instance element: missing `id` attribute');
+	}
+};
+
+type AssertDOMSecondaryInstanceElements = (
+	elements: readonly DOMInstanceElement[]
+) => asserts elements is readonly DOMSecondaryInstanceElement[];
+
+const assertDOMSecondaryInstanceElements: AssertDOMSecondaryInstanceElements = (elements) => {
+	elements.forEach(assertDOMSecondaryInstanceElement);
+};
 
 const domParser = new DOMParser();
 
@@ -145,61 +177,33 @@ const normalizeRepeatGroups = (body: Element): void => {
 	}
 };
 
-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.
+ * Performs preprocess operations to normalize certain aspects of the body of an
+ * XForm, for consistency when parsing 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`
+ * - 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;
+const normalizeXFormBody = <T extends Element>(body: T): T => {
+	normalizeBodyRefNodesetAttributes(body);
+	normalizeRepeatGroups(body);
 
-	if (options.isNormalized) {
-		normalizedXML = sourceXML;
-	} else {
-		normalizeBodyRefNodesetAttributes(body);
-		normalizeRepeatGroups(body);
-
-		normalizedXML = html.outerHTML;
-	}
-
-	return {
-		xformDocument,
-		rootEvaluator,
-		html,
-		body,
-		normalizedXML,
-	};
+	return body;
 };
 
+interface XFormDOMOptions {
+	readonly isNormalized: boolean;
+}
+
+/**
+ * @todo **Everything** in this class should be cacheable. Maybe not worth it
+ * for small forms, but may make a pretty substantial difference for very large
+ * forms (in bytes) in sessions creating multiple instances of the same form.
+ */
 export class XFormDOM {
 	static from(sourceXML: string) {
 		return new this(sourceXML, { isNormalized: false });
@@ -207,10 +211,6 @@ export class XFormDOM {
 
 	protected readonly normalizedXML: string;
 
-	// XPath
-	readonly rootEvaluator: XFormsXPathEvaluator;
-	readonly primaryInstanceEvaluator: XFormsXPathEvaluator;
-
 	// Commonly accessed landmark nodes
 	readonly xformDocument: XMLDocument;
 
@@ -220,59 +220,94 @@ export class XFormDOM {
 	readonly title: Element;
 
 	readonly model: Element;
+	readonly binds: readonly DOMBindElement[];
 	readonly primaryInstance: Element;
 	readonly primaryInstanceRoot: Element;
 
+	readonly itextTranslationElements: readonly DOMItextTranslationElement[];
+	readonly secondaryInstanceElements: readonly DOMSecondaryInstanceElement[];
+
 	readonly body: Element;
 
 	protected constructor(
 		protected readonly sourceXML: string,
-		options: XFormDOMNormalizationOptions
+		options: XFormDOMOptions
 	) {
-		const normalizedXForm: NormalizedXForm = parseNormalizedXForm(sourceXML, options);
-		const { xformDocument, html, body, rootEvaluator, normalizedXML } = normalizedXForm;
-		const head = rootEvaluator.evaluateNonNullElement('./h:head', {
+		const evaluator = new DefaultEvaluator();
+		const xformDocument: XMLDocument = domParser.parseFromString(sourceXML, 'text/xml');
+		const html = evaluator.evaluateNonNullElement('/h:html', {
+			contextNode: xformDocument,
+		});
+
+		let body = evaluator.evaluateNonNullElement('./h:body', {
 			contextNode: html,
 		});
-		const title = rootEvaluator.evaluateNonNullElement('./h:title', {
+		let normalizedXML: string;
+
+		if (options.isNormalized) {
+			normalizedXML = sourceXML;
+		} else {
+			body = normalizeXFormBody(body);
+
+			// TODO: if we keep doing normalization this way long term (or using the DOM
+			// for parsing long term, for that matter!), we should measure this. And we
+			// should measure against XMLSerializer while we're at it!
+			normalizedXML = xformDocument.documentElement.outerHTML;
+		}
+
+		const head = evaluator.evaluateNonNullElement('./h:head', {
+			contextNode: html,
+		});
+		const title = evaluator.evaluateNonNullElement('./h:title', {
 			contextNode: head,
 		});
-		const model = rootEvaluator.evaluateNonNullElement('./xf:model', {
+		const model = evaluator.evaluateNonNullElement('./xf:model', {
 			contextNode: head,
 		});
-		// TODO: Evidently primary instance root will not always have an id
-		const primaryInstanceRoot = rootEvaluator.evaluateNonNullElement('./xf:instance/*[@id]', {
+		const binds = evaluator.evaluateNodes<DOMBindElement>('./xf:bind[@nodeset]', {
 			contextNode: model,
 		});
-		// TODO: invert primary instance/root lookups
-		const primaryInstance = rootEvaluator.evaluateNonNullElement('..', {
-			contextNode: primaryInstanceRoot,
+
+		const instances = evaluator.evaluateNodes<DOMInstanceElement>('./xf:instance', {
+			contextNode: model,
 		});
 
-		this.normalizedXML = normalizedXML;
-		this.rootEvaluator = rootEvaluator;
-		this.primaryInstanceEvaluator = new XFormsXPathEvaluator({
-			rootNode: primaryInstance,
+		const [primaryInstance, ...secondaryInstanceElements] = instances;
+
+		assertDOMSecondaryInstanceElements(secondaryInstanceElements);
+
+		if (primaryInstance == null) {
+			throw new Error('Form is missing primary instance');
+		}
+
+		// TODO: Evidently primary instance root will not always have an id
+		const primaryInstanceRoot = evaluator.evaluateNonNullElement('./*[@id]', {
+			contextNode: primaryInstance,
 		});
+
+		const itextTranslationElements = evaluator.evaluateNodes<DOMItextTranslationElement>(
+			'./xf:itext/xf:translation[@lang]',
+			{
+				contextNode: model,
+			}
+		);
+
+		this.normalizedXML = normalizedXML;
 		this.xformDocument = xformDocument;
 		this.html = html;
 		this.head = head;
 		this.title = title;
 		this.model = model;
+		this.binds = binds;
 		this.primaryInstance = primaryInstance;
 		this.primaryInstanceRoot = primaryInstanceRoot;
+		this.itextTranslationElements = itextTranslationElements;
+		this.secondaryInstanceElements = secondaryInstanceElements;
 		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,

package/src/{XFormDefinition.ts → parse/XFormDefinition.ts}

@@ -1,9 +1,8 @@
-import { XFormDOM } from './XFormDOM.ts';
-import { BodyDefinition } from './body/BodyDefinition.ts';
+import { BodyDefinition } from '../parse/body/BodyDefinition.ts';
 import { ModelDefinition } from './model/ModelDefinition.ts';
+import { XFormDOM } from './XFormDOM.ts';
 
 export class XFormDefinition {
-	readonly xformDOM: XFormDOM;
 	readonly xformDocument: XMLDocument;
 
 	readonly id: string;
@@ -14,11 +13,7 @@ export class XFormDefinition {
 	readonly body: BodyDefinition;
 	readonly model: ModelDefinition;
 
-	constructor(readonly sourceXML: string) {
-		const xformDOM = XFormDOM.from(sourceXML);
-
-		this.xformDOM = xformDOM;
-
+	constructor(readonly xformDOM: XFormDOM) {
 		const { primaryInstanceRoot, title, xformDocument } = xformDOM;
 		const id = primaryInstanceRoot.getAttribute('id');
 

package/src/parse/attachments/FormAttachmentResource.ts

@@ -0,0 +1,40 @@
+import type { JRResourceURL } from '@getodk/common/jr-resources/JRResourceURL.ts';
+
+export type FormAttachmentDataType = 'media' | 'secondary-instance';
+
+/**
+ * @todo This type anticipates work to support media form attachments, which
+ * will tend to be associated with binary data. The
+ * expectation is that:
+ *
+ * - {@link Blob} would be appropriate for representing data from attachment
+ *   resources which are conventionally loaded to completion (where network
+ *   conditions are favorable), such as images
+ *
+ * - {@link MediaSource} or {@link ReadableStream} may be more appropriate for
+ *   representing data from resources which are conventionally streamed in a
+ *   browser context (often regardless of network conditions), such as video and
+ *   audio
+ */
+// prettier-ignore
+export type FormAttachmentMediaData =
+	| Blob
+	| MediaSource
+	| ReadableStream<unknown>;
+
+export type FormAttachmentSecondaryInstanceData = string;
+
+// prettier-ignore
+type FormAttachmentData<DataType extends FormAttachmentDataType> =
+	DataType extends 'media'
+		? FormAttachmentMediaData
+		: FormAttachmentSecondaryInstanceData;
+
+export abstract class FormAttachmentResource<DataType extends FormAttachmentDataType> {
+	protected constructor(
+		readonly dataType: DataType,
+		readonly resourceURL: JRResourceURL,
+		readonly contentType: string,
+		readonly data: FormAttachmentData<DataType>
+	) {}
+}