@getodk/xforms-engine 0.14.0 → 0.15.0

package/src/lib/xml-serialization.ts

@@ -1,3 +1,5 @@
+import type { GeneralChildNode } from '../client/hierarchy.ts';
+import type { Attribute } from '../instance/Attribute.ts';
 import type { NamespaceDeclarationMap } from './names/NamespaceDeclarationMap.ts';
 import type { QualifiedName } from './names/QualifiedName.ts';
 
@@ -78,15 +80,6 @@ export const escapeXMLText = <Text extends string>(
 		: (out as EscapedXMLText);
 };
 
-interface SerializableElementAttribute {
-	serializeAttributeXML(): string;
-}
-
-interface ElementXMLSerializationOptions {
-	readonly namespaceDeclarations?: NamespaceDeclarationMap;
-	readonly attributes?: readonly SerializableElementAttribute[];
-}
-
 const serializeElementNamespaceDeclarationXML = (
 	namespaceDeclarations?: NamespaceDeclarationMap
 ): string => {
@@ -103,24 +96,11 @@ const serializeElementNamespaceDeclarationXML = (
 		.join('');
 };
 
-const serializeElementAttributeXML = (
-	attributes?: readonly SerializableElementAttribute[]
-): string => {
-	if (attributes == null) {
-		return '';
-	}
-
-	return attributes
-		.map((attribute) => {
-			return attribute.serializeAttributeXML();
-		})
-		.join('');
-};
-
 const serializeElementXML = (
 	qualifiedName: QualifiedName,
 	children: string,
-	options: ElementXMLSerializationOptions = {}
+	attributes: string,
+	namespaceDeclarations?: NamespaceDeclarationMap
 ): string => {
 	// See JSDoc for the `getPrefixedName` method. If we find we do actually need
 	// custom element (subtree) prefix resolution, we'd uncomment the argument
@@ -133,11 +113,9 @@ const serializeElementXML = (
 	const nodeName = qualifiedName.getPrefixedName(
 		// options.namespaceDeclarations
 	);
-	const namespaceDeclarations = serializeElementNamespaceDeclarationXML(
-		options.namespaceDeclarations
-	);
-	const attributes = serializeElementAttributeXML(options.attributes);
-	const prefix = `<${nodeName}${namespaceDeclarations}${attributes}`;
+	const serializedNamespaceDeclarations =
+		serializeElementNamespaceDeclarationXML(namespaceDeclarations);
+	const prefix = `<${nodeName}${serializedNamespaceDeclarations}${attributes}`;
 
 	if (children === '') {
 		return `${prefix}/>`;
@@ -146,18 +124,36 @@ const serializeElementXML = (
 	return `${prefix}>${children}</${nodeName}>`;
 };
 
+export const serializeAttributeXML = (
+	qualifiedName: QualifiedName,
+	xmlValue: EscapedXMLText
+): string => {
+	const nodeName = qualifiedName.getPrefixedName();
+	return ` ${nodeName}="${xmlValue.normalize()}"`;
+};
+
 export const serializeParentElementXML = (
 	qualifiedName: QualifiedName,
-	serializedChildren: readonly string[],
-	options?: ElementXMLSerializationOptions
+	children: readonly GeneralChildNode[],
+	attributes: readonly Attribute[],
+	namespaceDeclarations?: NamespaceDeclarationMap
 ): string => {
-	return serializeElementXML(qualifiedName, serializedChildren.join(''), options);
+	const serializedChildren = children.map((child) => child.instanceState.instanceXML).join('');
+	const serializedAttributes = attributes
+		.map((attribute) => attribute.instanceState.instanceXML)
+		.join('');
+	return serializeElementXML(
+		qualifiedName,
+		serializedChildren,
+		serializedAttributes,
+		namespaceDeclarations
+	);
 };
 
 export const serializeLeafElementXML = (
 	qualifiedName: QualifiedName,
 	xmlValue: EscapedXMLText,
-	options?: ElementXMLSerializationOptions
+	namespaceDeclarations?: NamespaceDeclarationMap
 ): string => {
-	return serializeElementXML(qualifiedName, xmlValue.normalize(), options);
+	return serializeElementXML(qualifiedName, xmlValue.normalize(), '', namespaceDeclarations);
 };

package/src/parse/model/AttributeDefinition.ts

@@ -0,0 +1,58 @@
+import { XMLNS_NAMESPACE_URI } from '@getodk/common/constants/xmlns.ts';
+import type { StaticAttribute } from '../../integration/xpath/static-dom/StaticAttribute.ts';
+import {
+	NamespaceDeclarationMap,
+	type NamedNodeDefinition,
+} from '../../lib/names/NamespaceDeclarationMap.ts';
+import { QualifiedName } from '../../lib/names/QualifiedName.ts';
+import { escapeXMLText, serializeAttributeXML } from '../../lib/xml-serialization.ts';
+import type { BindDefinition } from './BindDefinition.ts';
+import { NodeDefinition } from './NodeDefinition.ts';
+import type { RootDefinition } from './RootDefinition.ts';
+
+export class AttributeDefinition
+	extends NodeDefinition<'attribute'>
+	implements NamedNodeDefinition
+{
+	private readonly serializedXML: string;
+
+	readonly value: string;
+	readonly type = 'attribute';
+	readonly namespaceDeclarations: NamespaceDeclarationMap;
+	readonly bodyElement = null;
+	readonly root: RootDefinition;
+	readonly isTranslated: boolean = false;
+	readonly parent = null;
+	readonly children = null;
+	readonly attributes = null;
+
+	readonly qualifiedName: QualifiedName;
+
+	constructor(
+		root: RootDefinition,
+		bind: BindDefinition,
+		readonly template: StaticAttribute
+	) {
+		super(bind);
+
+		const { value } = template;
+
+		this.root = root;
+
+		this.value = value;
+		this.qualifiedName = template.qualifiedName;
+		this.namespaceDeclarations = new NamespaceDeclarationMap(this);
+
+		// We serialize namespace declarations separately
+		if (this.qualifiedName.namespaceURI?.href === XMLNS_NAMESPACE_URI) {
+			this.serializedXML = '';
+		} else {
+			const xmlValue = escapeXMLText(this.value, true);
+			this.serializedXML = serializeAttributeXML(this.qualifiedName, xmlValue);
+		}
+	}
+
+	serializeAttributeXML(): string {
+		return this.serializedXML;
+	}
+}

package/src/parse/model/{RootAttributeMap.ts → AttributeDefinitionMap.ts}

@@ -2,8 +2,8 @@ import { XMLNS_NAMESPACE_URI } from '@getodk/common/constants/xmlns.ts';
 import type { StaticAttribute } from '../../integration/xpath/static-dom/StaticAttribute.ts';
 import type { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
 import type { QualifiedName } from '../../lib/names/QualifiedName.ts';
-import { RootAttributeDefinition } from './RootAttributeDefinition.ts';
-import type { RootDefinition } from './RootDefinition.ts';
+import { AttributeDefinition } from './AttributeDefinition.ts';
+import type { ModelDefinition } from './ModelDefinition.ts';
 
 /**
  * @todo We should probably just distinguish these as separate `StaticNode`
@@ -14,12 +14,6 @@ const isNonNamespaceAttribute = (attribute: StaticAttribute) => {
 };
 
 /**
- * @todo This can be trivially expanded to a narrowly general case when we
- * prioritize work to
- * {@link https://github.com/getodk/web-forms/issues/285 | support attributes}
- * (as modeled form nodes on par with elements). It's been deferred here to
- * avoid expanding scope of an already fairly large yak shave.
- *
  * @todo There's a **much more expansive** general case just waiting for a good
  * opportuntity to prioritize it. E.g. a `NamedNodeMap<T>`, where T is any
  * generalized concept of a named node. This expansive generalization would have
@@ -29,17 +23,17 @@ const isNonNamespaceAttribute = (attribute: StaticAttribute) => {
  *
  * @see {@link QualifiedName} for more detail.
  */
-export class RootAttributeMap extends Map<QualifiedName, RootAttributeDefinition> {
-	static from(root: RootDefinition, instanceNode: StaticElement) {
+export class AttributeDefinitionMap extends Map<QualifiedName, AttributeDefinition> {
+	static from(model: ModelDefinition, instanceNode: StaticElement) {
 		const nonNamespaceAttributes = instanceNode.attributes.filter(isNonNamespaceAttribute);
 		const definitions = nonNamespaceAttributes.map((attribute) => {
-			return new RootAttributeDefinition(root, attribute);
+			const bind = model.binds.getOrCreateBindDefinition(attribute.nodeset);
+			return new AttributeDefinition(model.root, bind, attribute);
 		});
-
 		return new this(definitions);
 	}
 
-	private constructor(definitions: readonly RootAttributeDefinition[]) {
+	private constructor(definitions: readonly AttributeDefinition[]) {
 		super(
 			definitions.map((attribute) => {
 				return [attribute.qualifiedName, attribute];

package/src/parse/model/GroupDefinition.ts

@@ -3,8 +3,10 @@ import { NamespaceDeclarationMap } from '../../lib/names/NamespaceDeclarationMap
 import { QualifiedName } from '../../lib/names/QualifiedName.ts';
 import type { AnyBodyElementDefinition } from '../body/BodyDefinition.ts';
 import type { GroupElementDefinition } from '../body/GroupElementDefinition.ts';
+import { AttributeDefinitionMap } from './AttributeDefinitionMap.ts';
 import type { BindDefinition } from './BindDefinition.ts';
 import { DescendentNodeDefinition } from './DescendentNodeDefinition.ts';
+import type { ModelDefinition } from './ModelDefinition.ts';
 import type { ChildNodeDefinition, ParentNodeDefinition } from './NodeDefinition.ts';
 
 export class GroupDefinition extends DescendentNodeDefinition<
@@ -16,8 +18,10 @@ export class GroupDefinition extends DescendentNodeDefinition<
 	readonly namespaceDeclarations: NamespaceDeclarationMap;
 	readonly qualifiedName: QualifiedName;
 	readonly children: readonly ChildNodeDefinition[];
+	readonly attributes: AttributeDefinitionMap;
 
 	constructor(
+		model: ModelDefinition,
 		parent: ParentNodeDefinition,
 		bind: BindDefinition,
 		bodyElement: AnyBodyElementDefinition | null,
@@ -37,6 +41,8 @@ export class GroupDefinition extends DescendentNodeDefinition<
 		this.qualifiedName = template.qualifiedName;
 		this.namespaceDeclarations = new NamespaceDeclarationMap(this);
 		this.children = root.buildSubtree(this, template);
+
+		this.attributes = AttributeDefinitionMap.from(model, template);
 	}
 
 	toJSON() {

package/src/parse/model/LeafNodeDefinition.ts

@@ -20,6 +20,7 @@ export class LeafNodeDefinition<V extends ValueType = ValueType>
 	readonly namespaceDeclarations: NamespaceDeclarationMap;
 	readonly qualifiedName: QualifiedName;
 	readonly children = null;
+	readonly attributes = null;
 
 	constructor(
 		parent: ParentNodeDefinition,

package/src/parse/model/NodeDefinition.ts

@@ -1,3 +1,4 @@
+import type { StaticAttribute } from '../../integration/xpath/static-dom/StaticAttribute.ts';
 import type { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
 import type {
 	NamedSubtreeDefinition,
@@ -6,6 +7,8 @@ import type {
 import type { QualifiedName } from '../../lib/names/QualifiedName.ts';
 import type { AnyBodyElementDefinition } from '../body/BodyDefinition.ts';
 import type { RepeatElementDefinition } from '../body/RepeatElementDefinition.ts';
+import type { AttributeDefinition } from './AttributeDefinition.ts';
+import type { AttributeDefinitionMap } from './AttributeDefinitionMap.ts';
 import type { BindDefinition } from './BindDefinition.ts';
 import type { GroupDefinition } from './GroupDefinition.ts';
 import type { LeafNodeDefinition } from './LeafNodeDefinition.ts';
@@ -45,13 +48,16 @@ export type GroupNodeType = 'group';
  */
 export type LeafNodeType = 'leaf-node';
 
+export type AttributeNodeType = 'attribute';
+
 // prettier-ignore
 export type NodeDefinitionType =
 	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
 	| RootNodeType
 	| RepeatType
 	| GroupNodeType
-	| LeafNodeType;
+	| LeafNodeType
+	| AttributeNodeType;
 
 // prettier-ignore
 export type ParentNodeDefinition =
@@ -76,8 +82,9 @@ export abstract class NodeDefinition<Type extends NodeDefinitionType>
 	abstract readonly isTranslated: boolean;
 	abstract readonly root: RootDefinition;
 	abstract readonly parent: ParentNodeDefinition | null;
-	abstract readonly template: StaticElement;
+	abstract readonly template: StaticAttribute | StaticElement;
 	abstract readonly children: readonly ChildNodeDefinition[] | null;
+	abstract readonly attributes: AttributeDefinitionMap | null;
 
 	readonly nodeset: string;
 
@@ -92,4 +99,5 @@ export type AnyNodeDefinition =
 	| RootDefinition
 	| AnyRepeatDefinition
 	| GroupDefinition
-	| LeafNodeDefinition;
+	| LeafNodeDefinition
+	| AttributeDefinition;

package/src/parse/model/RepeatDefinition.ts

@@ -19,9 +19,11 @@ import type { NamespaceURL } from '../../lib/names/NamespaceURL.ts';
 import type { QualifiedName, QualifiedNameSource } from '../../lib/names/QualifiedName.ts';
 import type { RepeatElementDefinition } from '../body/RepeatElementDefinition.ts';
 import { RepeatCountControlExpression } from '../expression/RepeatCountControlExpression.ts';
+import { AttributeDefinitionMap } from './AttributeDefinitionMap.ts';
 import type { BindDefinition } from './BindDefinition.ts';
 import { DescendentNodeDefinition } from './DescendentNodeDefinition.ts';
 import type { GroupDefinition } from './GroupDefinition.ts';
+import type { ModelDefinition } from './ModelDefinition.ts';
 import type { ChildNodeDefinition, ParentNodeDefinition } from './NodeDefinition.ts';
 import type { RootDefinition } from './RootDefinition.ts';
 
@@ -313,18 +315,20 @@ export interface UncontrolledRepeatDefinition extends RepeatDefinition {
  */
 export class RepeatDefinition extends DescendentNodeDefinition<'repeat', RepeatElementDefinition> {
 	static from(
+		model: ModelDefinition,
 		parent: ParentNodeDefinition,
 		bind: BindDefinition,
 		bodyElement: RepeatElementDefinition,
 		instanceNodes: RepeatInstanceNodes
 	): AnyRepeatDefinition;
 	static from(
+		model: ModelDefinition,
 		parent: ParentNodeDefinition,
 		bind: BindDefinition,
 		bodyElement: RepeatElementDefinition,
 		instanceNodes: RepeatInstanceNodes
 	): RepeatDefinition {
-		return new this(parent, bind, bodyElement, instanceNodes);
+		return new this(model, parent, bind, bodyElement, instanceNodes);
 	}
 
 	readonly type = 'repeat';
@@ -333,8 +337,10 @@ export class RepeatDefinition extends DescendentNodeDefinition<'repeat', RepeatE
 	readonly template: StaticElement;
 	readonly namespaceDeclarations: NamespaceDeclarationMap;
 	readonly qualifiedName: QualifiedName;
+	readonly attributes: AttributeDefinitionMap;
 
 	private constructor(
+		model: ModelDefinition,
 		parent: ParentNodeDefinition,
 		bind: BindDefinition,
 		bodyElement: RepeatElementDefinition,
@@ -353,6 +359,7 @@ export class RepeatDefinition extends DescendentNodeDefinition<'repeat', RepeatE
 		this.children = root.buildSubtree(self, template);
 
 		const initialCount = this.omitTemplate(instanceNodes).length;
+		this.attributes = AttributeDefinitionMap.from(model, template);
 
 		this.count = RepeatCountControlExpression.from(bodyElement, initialCount);
 	}

package/src/parse/model/RootDefinition.ts

@@ -3,6 +3,7 @@ import { NamespaceDeclarationMap } from '../../lib/names/NamespaceDeclarationMap
 import { QualifiedName } from '../../lib/names/QualifiedName.ts';
 import type { BodyClassList } from '../body/BodyDefinition.ts';
 import type { XFormDefinition } from '../XFormDefinition.ts';
+import { AttributeDefinitionMap } from './AttributeDefinitionMap.ts';
 import { GroupDefinition } from './GroupDefinition.ts';
 import { LeafNodeDefinition } from './LeafNodeDefinition.ts';
 import type { ModelDefinition } from './ModelDefinition.ts';
@@ -11,7 +12,6 @@ import { NodeDefinition } from './NodeDefinition.ts';
 import { NoteNodeDefinition } from './NoteNodeDefinition.ts';
 import { RangeNodeDefinition } from './RangeNodeDefinition.ts';
 import { RepeatDefinition } from './RepeatDefinition.ts';
-import { RootAttributeMap } from './RootAttributeMap.ts';
 import type { SubmissionDefinition } from './SubmissionDefinition.ts';
 
 export class RootDefinition extends NodeDefinition<'root'> {
@@ -22,7 +22,7 @@ export class RootDefinition extends NodeDefinition<'root'> {
 	readonly parent = null;
 	readonly template: StaticElement;
 	readonly namespaceDeclarations: NamespaceDeclarationMap;
-	readonly attributes: RootAttributeMap;
+	readonly attributes: AttributeDefinitionMap;
 	readonly children: readonly ChildNodeDefinition[];
 
 	readonly isTranslated = false;
@@ -51,7 +51,7 @@ export class RootDefinition extends NodeDefinition<'root'> {
 
 		this.qualifiedName = qualifiedName;
 		this.template = template;
-		this.attributes = RootAttributeMap.from(this, template);
+		this.attributes = AttributeDefinitionMap.from(model, template);
 		this.namespaceDeclarations = new NamespaceDeclarationMap(this);
 		this.children = this.buildSubtree(this, template);
 	}
@@ -87,7 +87,7 @@ export class RootDefinition extends NodeDefinition<'root'> {
 			const [firstChild, ...restChildren] = children;
 
 			if (bodyElement?.type === 'repeat') {
-				return RepeatDefinition.from(parent, bind, bodyElement, children);
+				return RepeatDefinition.from(model, parent, bind, bodyElement, children);
 			}
 
 			if (restChildren.length) {
@@ -107,7 +107,7 @@ export class RootDefinition extends NodeDefinition<'root'> {
 				);
 			}
 
-			return new GroupDefinition(parent, bind, bodyElement, element);
+			return new GroupDefinition(model, parent, bind, bodyElement, element);
 		});
 	}
 

package/src/parse/model/nodeDefinitionMap.ts

@@ -16,7 +16,7 @@ const collectDefinitions = (
 
 	result.set(nodeset, definition);
 
-	if (definition.type === 'leaf-node') {
+	if (definition.type === 'leaf-node' || definition.type === 'attribute') {
 		return result;
 	}
 

package/dist/error/TemplatedNodeAttributeSerializationError.d.ts

@@ -1,22 +0,0 @@
-/**
- * This error class is intended as a common point of reference for all of the
- * related interfaces and implementation where we've deferred two concerns:
- *
- * 1. Support for attributes on instance nodes (which may be bound in a form's
- *    model and/or may be expected to preserve model-defined defaults)
- * 2. Present lack of logic to treat a `jr:template` attribute as a special
- *    case: whereas in the general case we would expect to pass through a
- *    form/model-defined attribute, we expect to specifically **omit**
- *    `jr:template` from repeat instances derived from any of form's
- *    explicitly-defined repeat templates
- *
- * Addressing #1 is (now) a prerequisite to addressing #2, and it is also a
- * prerequisite for #2's unaddressed status to _become meaningfully observable
- * and problematic_.
- *
- * By introducing this error at a point where a change in #1's status is likely
- * to be implicated, we're also likely to be reminded to address #2 in tandem.
- */
-export declare class TemplatedNodeAttributeSerializationError extends Error {
-    constructor();
-}

package/dist/parse/model/RootAttributeDefinition.d.ts

@@ -1,21 +0,0 @@
-import { NamedNodeDefinition } from '../../lib/names/NamespaceDeclarationMap.ts';
-import { QualifiedName } from '../../lib/names/QualifiedName.ts';
-import { RootDefinition } from './RootDefinition.ts';
-interface RootAttributeSource {
-    readonly qualifiedName: QualifiedName;
-    readonly value: string;
-}
-/**
- * @todo This class is named and typed to emphasize its intentionally narrow
- * usage and purpose. It **intentionally** avoids addressing the much broader
- * set of concerns around modeling attributes in primary instance/submissions.
- */
-export declare class RootAttributeDefinition implements NamedNodeDefinition {
-    private readonly serializedXML;
-    readonly parent: RootDefinition;
-    readonly qualifiedName: QualifiedName;
-    readonly value: string;
-    constructor(root: RootDefinition, source: RootAttributeSource);
-    serializeAttributeXML(): string;
-}
-export {};

package/src/error/TemplatedNodeAttributeSerializationError.ts

@@ -1,24 +0,0 @@
-/**
- * This error class is intended as a common point of reference for all of the
- * related interfaces and implementation where we've deferred two concerns:
- *
- * 1. Support for attributes on instance nodes (which may be bound in a form's
- *    model and/or may be expected to preserve model-defined defaults)
- * 2. Present lack of logic to treat a `jr:template` attribute as a special
- *    case: whereas in the general case we would expect to pass through a
- *    form/model-defined attribute, we expect to specifically **omit**
- *    `jr:template` from repeat instances derived from any of form's
- *    explicitly-defined repeat templates
- *
- * Addressing #1 is (now) a prerequisite to addressing #2, and it is also a
- * prerequisite for #2's unaddressed status to _become meaningfully observable
- * and problematic_.
- *
- * By introducing this error at a point where a change in #1's status is likely
- * to be implicated, we're also likely to be reminded to address #2 in tandem.
- */
-export class TemplatedNodeAttributeSerializationError extends Error {
-	constructor() {
-		super('Template attribute omission not implemented');
-	}
-}

package/src/parse/model/RootAttributeDefinition.ts

@@ -1,44 +0,0 @@
-import { XMLNS_NAMESPACE_URI } from '@getodk/common/constants/xmlns.ts';
-import type { NamedNodeDefinition } from '../../lib/names/NamespaceDeclarationMap.ts';
-import { QualifiedName } from '../../lib/names/QualifiedName.ts';
-import { escapeXMLText } from '../../lib/xml-serialization.ts';
-import type { RootDefinition } from './RootDefinition.ts';
-
-interface RootAttributeSource {
-	readonly qualifiedName: QualifiedName;
-	readonly value: string;
-}
-
-/**
- * @todo This class is named and typed to emphasize its intentionally narrow
- * usage and purpose. It **intentionally** avoids addressing the much broader
- * set of concerns around modeling attributes in primary instance/submissions.
- */
-export class RootAttributeDefinition implements NamedNodeDefinition {
-	private readonly serializedXML: string;
-
-	readonly parent: RootDefinition;
-	readonly qualifiedName: QualifiedName;
-	readonly value: string;
-
-	constructor(root: RootDefinition, source: RootAttributeSource) {
-		const { qualifiedName, value } = source;
-
-		this.parent = root;
-		this.qualifiedName = qualifiedName;
-		this.value = value;
-
-		// We serialize namespace declarations separately
-		if (qualifiedName.namespaceURI?.href === XMLNS_NAMESPACE_URI) {
-			this.serializedXML = '';
-		} else {
-			const nodeName = qualifiedName.getPrefixedName();
-
-			this.serializedXML = ` ${nodeName}="${escapeXMLText(value, true)}"`;
-		}
-	}
-
-	serializeAttributeXML(): string {
-		return this.serializedXML;
-	}
-}