@getodk/xforms-engine 0.5.0 → 0.7.0

package/src/lib/names/QualifiedName.ts

@@ -0,0 +1,170 @@
+import type { XPathDOMAdapter } from '@getodk/xpath';
+import { NamespaceURL } from './NamespaceURL.ts';
+
+export type NamespaceURI = NamespaceURL | null;
+export type QualifiedNamePrefix = string | null;
+
+export interface NamespaceQualifiedNameSource {
+	readonly namespaceURI: NamespaceURI | string;
+	readonly localName: string;
+
+	/**
+	 * Note that this property is intentionally optional as one of the
+	 * {@link QualifiedNameSource | QualifiedName source input}, and its absence
+	 * is treated differently from an explicitly assigned `null` value.
+	 *
+	 * @see {@link SourcePrefixUnspecified}, {@link DeferredPrefix}
+	 */
+	readonly prefix?: QualifiedNamePrefix;
+}
+
+const SOURCE_PREFIX_UNSPECIFIED = Symbol('SOURCE_PREFIX_UNSPECIFIED');
+
+/**
+ * May be used as a placeholder for a {@link QualifiedName.prefix}, where the
+ * actual prefix may not be known at definition time.
+ *
+ * Example: parsing non-XML sources into an XML-like tree, e.g. for XPath
+ * evaluation; in which case, we may not need to resolve a prefix for the name
+ * until such a node is serialized as XML, if it ever is.
+ */
+type SourcePrefixUnspecified = typeof SOURCE_PREFIX_UNSPECIFIED;
+
+/**
+ * Represents a {@link QualifiedName.prefix} whose resolution may be deferred,
+ * e.g. until all requisite parsing is complete and/or until XML serialization
+ * requires use of a prefix to represent the corresponding
+ * {@link QualifiedName.namespaceURI}.
+ */
+// prettier-ignore
+type DeferredPrefix =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| string
+	| null
+	| SourcePrefixUnspecified;
+
+interface DeferredPrefixedQualifiedNameSource {
+	readonly namespaceURI: NamespaceURI | string;
+	readonly prefix: DeferredPrefix;
+	readonly localName: string;
+}
+
+// prettier-ignore
+export type QualifiedNameSource =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| NamespaceQualifiedNameSource
+	| DeferredPrefixedQualifiedNameSource;
+
+interface PrefixResolutionOptions {
+	lookupPrefix(namespaceURI: NamespaceURI | string): string | null;
+}
+
+/**
+ * @todo This is in the `lib` directory because it's a cross-cutting concern,
+ * applicable to:
+ *
+ * - Parsing XML into a useful runtime data model (usage which motivated initial
+ *   development of this class)
+ * - Serializing XML from a runtime data model (also motivated initial dev)
+ * - `@getodk/xpath` (internal) e.g. references to
+ *   {@link https://www.w3.org/TR/REC-xml-names/#NT-QName | QName} in various
+ *   parts of XPath expression _syntax_, as well as various parts of the package
+ *   interpreting those parts of syntax
+ * - `@getodk/xpath` (cross-package), e.g. in aspects of the
+ *   {@link XPathDOMAdapter} APIs, and implementations thereof
+ * - A zillion potential optimizations, e.g. where names are useful in a lookup
+ *   table (or used in conjunction with other information to construct keys for
+ *   same)
+ *
+ * @todo As a cross-cutting concern, there are subtle but important differences
+ * between certain XPath and XML semantics around expressions of a "null"
+ * {@link prefix}. E.g. in the expression `/foo`, **technically** the `foo` Step
+ * should select child elements _in the null namespace_, whereas in most other
+ * cases a null prefix (when explicitly assigned `null`, rather than
+ * {@link DeferredPrefix | deferred for later resolution}) is expected to
+ * correspond _to the default namespace_ (whatever that is in the context of the
+ * {@link QualifiedName | qualified-named thing}).
+ *
+ * @todo As a mechanism for many optimizations, an evolution of this class would
+ * be **BY FAR** most useful if it can be treated as a _value type_, despite
+ * challenges using non-primitives as such in a JS runtime. To be clear: it
+ * would be most useful if every instance of {@link QualifiedName} having the
+ * same property values (or in some cases, the same combined
+ * {@link namespaceURI}/{@link localName} or combined
+ * {@link prefix}/{@link localName}) would also have _reference equality_ with
+ * other instances having the same property values (or pertinent subset
+ * thereof). Making a somewhat obvious point explicit: this would be
+ * particularly useful in cases where a lookup table is implemented as a native
+ * {@link Map}, where using {@link QualifiedName} as a key would break
+ * expectations (and probably quite a lot of functionality!) if 2+ equivalent
+ * keys mapped to different values.
+ *
+ * @todo Where we would want to treat instances as a value type, it would be
+ * useful to look at prior art for representation of the same data as a string.
+ * One frame of reference worth looking at is
+ * {@link https://www.w3.org/TR/xpath-30/#prod-xpath30-URIQualifiedName | XPath 3.0's URIQualifiedName}
+ * (but note that this syntax is mutually exclusive with the prefixed `QName`).
+ */
+export class QualifiedName implements DeferredPrefixedQualifiedNameSource {
+	private readonly defaultPrefixResolutionOptions: PrefixResolutionOptions;
+
+	readonly namespaceURI: NamespaceURI;
+
+	/**
+	 * @see {@link SourcePrefixUnspecified}, {@link DeferredPrefix}
+	 */
+	readonly prefix: DeferredPrefix;
+
+	readonly localName: string;
+
+	constructor(source: QualifiedNameSource) {
+		const { localName } = source;
+
+		let prefix = source.prefix;
+
+		if (typeof prefix === 'undefined') {
+			prefix = SOURCE_PREFIX_UNSPECIFIED;
+		}
+
+		const namespaceURI = NamespaceURL.from(source.namespaceURI);
+
+		this.namespaceURI = namespaceURI;
+		this.prefix = prefix;
+		this.localName = localName;
+
+		this.defaultPrefixResolutionOptions = {
+			lookupPrefix: () => {
+				if (prefix === SOURCE_PREFIX_UNSPECIFIED) {
+					throw new Error(`Failed to resolve prefix for namespace URI: ${String(namespaceURI)}`);
+				}
+
+				return prefix;
+			},
+		};
+	}
+
+	/**
+	 * @todo at time of writing, it's not expected we will actually supply
+	 * {@link options} in calls to this method! Current calls are from definitions
+	 * whose prefixes are known at parse time (i.e. they are prefixed in the
+	 * source XML from which they're parsed).
+	 *
+	 * The intent of accepting the options here now is to leave a fairly large
+	 * breadcrumb, for any use case where we might want to serialize XML from
+	 * artificially constructed DOM-like trees (e.g. `StaticNode` implementations
+	 * defined by parsing non-XML external secondary instances such as CSV and
+	 * GeoJSON). AFAIK this doesn't correspond to any known feature in the "like
+	 * Collect" scope, but it could have implications for inspecting form details
+	 * in e.g. "debug/form design/dev mode" scenarios.
+	 */
+	getPrefixedName(options: PrefixResolutionOptions = this.defaultPrefixResolutionOptions): string {
+		const { namespaceURI, localName } = this;
+		const prefix = options.lookupPrefix(namespaceURI);
+
+		if (prefix == null) {
+			return localName;
+		}
+
+		return `${prefix}:${localName}`;
+	}
+}

package/src/lib/names/UnprefixedXFormsName.ts

@@ -0,0 +1,12 @@
+import { XFORMS_NAMESPACE_URI } from '@getodk/common/constants/xmlns.ts';
+import { QualifiedName } from './QualifiedName.ts';
+
+export class UnprefixedXFormsName extends QualifiedName {
+	constructor(localName: string) {
+		super({
+			namespaceURI: XFORMS_NAMESPACE_URI,
+			prefix: null,
+			localName,
+		});
+	}
+}

package/src/lib/number-parsers.ts

@@ -0,0 +1,25 @@
+export const parseToInteger = (value: string | null): number | null => {
+	if (value === null) {
+		return null;
+	}
+
+	const parsed = Number(value);
+	if (typeof value !== 'string' || value.trim() === '' || !Number.isInteger(parsed)) {
+		throw new Error(`Expected an integer, but got: ${value}`);
+	}
+
+	return parsed;
+};
+
+export const parseToFloat = (value: string | null): number | null => {
+	if (value === null) {
+		return null;
+	}
+
+	const parsed = Number(value);
+	if (typeof value !== 'string' || value.trim() === '' || Number.isNaN(parsed)) {
+		throw new Error(`Expected a float, but got: ${value}`);
+	}
+
+	return parsed;
+};

package/src/lib/reactivity/createInstanceValueState.ts

@@ -1,50 +1,27 @@
 import type { Signal } from 'solid-js';
 import { createComputed, createMemo, createSignal, untrack } from 'solid-js';
-import { ErrorProductionDesignPendingError } from '../../error/ErrorProductionDesignPendingError.ts';
 import type { InstanceValueContext } from '../../instance/internal-api/InstanceValueContext.ts';
 import type { BindComputationExpression } from '../../parse/expression/BindComputationExpression.ts';
 import { createComputedExpression } from './createComputedExpression.ts';
 import type { SimpleAtomicState, SimpleAtomicStateSetter } from './types.ts';
 
-type InitialValueSource = 'FORM_DEFAULT' | 'PRIMARY_INSTANCE';
-
-export interface InstanceValueStateOptions {
-	/**
-	 * Specifies the source of a {@link createInstanceValueState} signal's initial
-	 * value state, where:
-	 *
-	 * - 'FORM_DEFAULT': Derives the initial state from the form's definition of
-	 *   the node itself. This is the default option, appropriate when
-	 *   initializing a form without additional primary instance data. In other
-	 *   words, this value should not be used for edits.
-	 *
-	 * - 'PRIMARY_INSTANCE': Derives the initial state from the current text
-	 *   content of the {@link ValueNode.contextNode}. This option should be
-	 *   specified when initializing a form with existing primary instance data,
-	 *   such as when editing a previous submission.
-	 *
-	 * @default 'FORM_DEFAULT'
-	 *
-	 * Specifies whether a {@link createInstanceValueState} signal's initial state
-	 * should be derived from the current text content of the
-	 * {@link ValueNode.contextNode | primary instance DOM state}.
-	 */
-	readonly initialValueSource?: InitialValueSource;
-}
-
-const getInitialValue = (
-	context: InstanceValueContext,
-	options: InstanceValueStateOptions
-): string => {
-	const { initialValueSource = 'FORM_DEFAULT' } = options;
+const isInstanceFirstLoad = (context: InstanceValueContext) => {
+	return context.rootDocument.initializationMode === 'create';
+};
 
-	if (initialValueSource === 'FORM_DEFAULT') {
-		const { defaultValue } = context.definition;
+/**
+ * Special case, does not correspond to any event.
+ *
+ * @see {@link shouldPreloadUID}
+ */
+const isEditInitialLoad = (context: InstanceValueContext) => {
+	return context.rootDocument.initializationMode === 'edit';
+};
 
-		return context.decodeInstanceValue(defaultValue);
-	}
+const getInitialValue = (context: InstanceValueContext): string => {
+	const sourceNode = context.instanceNode ?? context.definition.template;
 
-	throw new ErrorProductionDesignPendingError('Edit implementation pending');
+	return context.decodeInstanceValue(sourceNode.value);
 };
 
 type BaseValueState = Signal<string>;
@@ -106,10 +83,56 @@ const guardDownstreamReadonlyWrites = (
 	return [getValue, setValue];
 };
 
+/**
+ * Per {@link https://getodk.github.io/xforms-spec/#preload-attributes:~:text=concatenation%20of%20%E2%80%98uuid%3A%E2%80%99%20and%20uuid()}
+ */
+const PRELOAD_UID_EXPRESSION = 'concat("uuid:", uuid())';
+
+/**
+ * @todo It feels increasingly awkward to keep piling up preload stuff here, but it won't stay that way for long. In the meantime, this seems like the best way to express the cases where `preload="uid"` should be effective, i.e.:
+ *
+ * - When an instance is first loaded ({@link isInstanceFirstLoad})
+ * - When an instance is initially loaded for editing ({@link isEditInitialLoad})
+ */
+const shouldPreloadUID = (context: InstanceValueContext) => {
+	return isInstanceFirstLoad(context) || isEditInitialLoad(context);
+};
+
+/**
+ * @todo This is a temporary one-off, until we support the full range of
+ * {@link https://getodk.github.io/xforms-spec/#preload-attributes | preloads}.
+ *
+ * @todo ALSO, IMPORTANTLY(!): the **call site** for this function is
+ * semantically where we would expect to trigger a
+ * {@link https://getodk.github.io/xforms-spec/#event:odk-instance-first-load | odk-instance-first-load event},
+ * _and compute_ preloads semantically associated with that event.
+ */
+const setPreloadUIDValue = (
+	context: InstanceValueContext,
+	valueState: RelevantValueState
+): void => {
+	const { preload } = context.definition.bind;
+
+	if (preload?.type !== 'uid' || !shouldPreloadUID(context)) {
+		return;
+	}
+
+	const preloadUIDValue = context.evaluator.evaluateString(PRELOAD_UID_EXPRESSION, {
+		contextNode: context.contextNode,
+	});
+
+	const [, setValue] = valueState;
+
+	setValue(preloadUIDValue);
+};
+
 /**
  * Defines a reactive effect which writes the result of `calculate` bind
  * computations to the provided value setter, on initialization and any
  * subsequent reactive update.
+ *
+ * @see {@link setPreloadUIDValue} for important details about spec ordering of
+ * events and computations.
  */
 const createCalculation = (
 	context: InstanceValueContext,
@@ -138,21 +161,24 @@ export type InstanceValueState = SimpleAtomicState<string>;
  * Provides a consistent interface for value nodes of any type which:
  *
  * - derives initial state from either an existing instance (e.g. for edits) or
- *   the node's definition (e.g. initializing a new submission)
+ *   the node's definition (e.g. initializing a new instance)
  * - decodes current primary instance state into the value node's runtime type
  * - encodes updated runtime values to store updated instance state
  * - initializes reactive computation of `calculate` bind expressions for those
  *   nodes defined with one
  * - prevents downstream writes to nodes in a readonly state
  */
-export const createInstanceValueState = (
-	context: InstanceValueContext,
-	options: InstanceValueStateOptions = {}
-): InstanceValueState => {
+export const createInstanceValueState = (context: InstanceValueContext): InstanceValueState => {
 	return context.scope.runTask(() => {
-		const initialValue = getInitialValue(context, options);
+		const initialValue = getInitialValue(context);
 		const baseValueState = createSignal(initialValue);
 		const relevantValueState = createRelevantValueState(context, baseValueState);
+
+		/**
+		 * @see {@link setPreloadUIDValue} for important details about spec ordering of events and computations.
+		 */
+		setPreloadUIDValue(context, relevantValueState);
+
 		const { calculate } = context.definition.bind;
 
 		if (calculate != null) {

package/src/lib/reactivity/{createSelectItems.ts → createItemCollection.ts}

@@ -1,21 +1,26 @@
 import { UpsertableMap } from '@getodk/common/lib/collections/UpsertableMap.ts';
 import type { Accessor } from 'solid-js';
 import { createMemo } from 'solid-js';
+import type { ActiveLanguage } from '../../client/FormLanguage.ts';
+import type { SelectItem } from '../../client/SelectNode.ts';
+import type { RankItem } from '../../client/RankNode.ts';
 import type { TextRange as ClientTextRange } from '../../client/TextRange.ts';
-import type { ActiveLanguage, SelectItem } from '../../index.ts';
 import type { EvaluationContext } from '../../instance/internal-api/EvaluationContext.ts';
 import type { TranslationContext } from '../../instance/internal-api/TranslationContext.ts';
-import type { SelectField } from '../../instance/SelectField.ts';
+import type { SelectControl } from '../../instance/SelectControl.ts';
+import type { RankControl } from '../../instance/RankControl.ts';
 import { TextChunk } from '../../instance/text/TextChunk.ts';
 import { TextRange } from '../../instance/text/TextRange.ts';
 import type { EngineXPathNode } from '../../integration/xpath/adapter/kind.ts';
 import type { EngineXPathEvaluator } from '../../integration/xpath/EngineXPathEvaluator.ts';
-import type { ItemDefinition } from '../../parse/body/control/select/ItemDefinition.ts';
-import type { ItemsetDefinition } from '../../parse/body/control/select/ItemsetDefinition.ts';
+import type { ItemDefinition } from '../../parse/body/control/ItemDefinition.ts';
+import type { ItemsetDefinition } from '../../parse/body/control/ItemsetDefinition.ts';
 import { createComputedExpression } from './createComputedExpression.ts';
 import type { ReactiveScope } from './scope.ts';
 import { createTextRange } from './text/createTextRange.ts';
 
+export type ItemCollectionControl = RankControl | SelectControl;
+type Item = RankItem | SelectItem;
 type DerivedItemLabel = ClientTextRange<'item-label', 'form-derived'>;
 
 const derivedItemLabel = (context: TranslationContext, value: string): DerivedItemLabel => {
@@ -24,7 +29,7 @@ const derivedItemLabel = (context: TranslationContext, value: string): DerivedIt
 	return new TextRange('form-derived', 'item-label', [chunk]);
 };
 
-const createSelectItemLabel = (
+const createItemLabel = (
 	context: EvaluationContext,
 	definition: ItemDefinition
 ): Accessor<ClientTextRange<'item-label'>> => {
@@ -37,14 +42,14 @@ const createSelectItemLabel = (
 	return createTextRange(context, 'item-label', label);
 };
 
-const createTranslatedStaticSelectItems = (
-	selectField: SelectField,
+const createTranslatedStaticItems = (
+	control: ItemCollectionControl,
 	items: readonly ItemDefinition[]
-): Accessor<readonly SelectItem[]> => {
-	return selectField.scope.runTask(() => {
+): Accessor<readonly Item[]> => {
+	return control.scope.runTask(() => {
 		const labeledItems = items.map((item) => {
 			const { value } = item;
-			const label = createSelectItemLabel(selectField, item);
+			const label = createItemLabel(control, item);
 
 			return () => ({
 				value,
@@ -66,18 +71,18 @@ class ItemsetItemEvaluationContext implements EvaluationContext {
 	readonly getActiveLanguage: Accessor<ActiveLanguage>;
 
 	constructor(
-		selectField: SelectField,
+		control: ItemCollectionControl,
 		readonly contextNode: EngineXPathNode
 	) {
-		this.isAttached = selectField.isAttached;
-		this.scope = selectField.scope;
-		this.evaluator = selectField.evaluator;
-		this.contextReference = selectField.contextReference;
-		this.getActiveLanguage = selectField.getActiveLanguage;
+		this.isAttached = control.isAttached;
+		this.scope = control.scope;
+		this.evaluator = control.evaluator;
+		this.contextReference = control.contextReference;
+		this.getActiveLanguage = control.getActiveLanguage;
 	}
 }
 
-const createSelectItemsetItemLabel = (
+const createItemsetItemLabel = (
 	context: EvaluationContext,
 	definition: ItemsetDefinition,
 	itemValue: Accessor<string>
@@ -99,11 +104,11 @@ interface ItemsetItem {
 }
 
 const createItemsetItems = (
-	selectField: SelectField,
+	control: ItemCollectionControl,
 	itemset: ItemsetDefinition
 ): Accessor<readonly ItemsetItem[]> => {
-	return selectField.scope.runTask(() => {
-		const itemNodes = createComputedExpression(selectField, itemset.nodes, {
+	return control.scope.runTask(() => {
+		const itemNodes = createComputedExpression(control, itemset.nodes, {
 			defaultValue: [],
 		});
 		const itemsCache = new UpsertableMap<EngineXPathNode, ItemsetItem>();
@@ -111,11 +116,11 @@ const createItemsetItems = (
 		return createMemo(() => {
 			return itemNodes().map((itemNode) => {
 				return itemsCache.upsert(itemNode, () => {
-					const context = new ItemsetItemEvaluationContext(selectField, itemNode);
+					const context = new ItemsetItemEvaluationContext(control, itemNode);
 					const value = createComputedExpression(context, itemset.value, {
 						defaultValue: '',
 					});
-					const label = createSelectItemsetItemLabel(context, itemset, value);
+					const label = createItemsetItemLabel(context, itemset, value);
 
 					return {
 						label,
@@ -128,11 +133,11 @@ const createItemsetItems = (
 };
 
 const createItemset = (
-	selectField: SelectField,
+	control: ItemCollectionControl,
 	itemset: ItemsetDefinition
-): Accessor<readonly SelectItem[]> => {
-	return selectField.scope.runTask(() => {
-		const itemsetItems = createItemsetItems(selectField, itemset);
+): Accessor<readonly Item[]> => {
+	return control.scope.runTask(() => {
+		const itemsetItems = createItemsetItems(control, itemset);
 
 		return createMemo(() => {
 			return itemsetItems().map((item) => {
@@ -146,23 +151,23 @@ const createItemset = (
 };
 
 /**
- * Creates a reactive computation of a {@link SelectField}'s
- * {@link SelectItem}s, in support of the field's `valueOptions`.
+ * Creates a reactive computation of a {@link ItemCollectionControl}'s
+ * {@link Item}s, in support of the field's `valueOptions`.
  *
- * - Selects defined with static `<item>`s will compute to an corresponding
+ * - The control defined with static `<item>`s will compute to an corresponding
  *   static list of items.
- * - Selects defined with a computed `<itemset>` will compute to a reactive list
+ * - The control defined with a computed `<itemset>` will compute to a reactive list
  *   of items.
- * - Items of both will produce {@link SelectItem.label | labels} reactive to
+ * - Items of both will produce {@link ItemType.label | labels} reactive to
  *   their appropriate dependencies (whether relative to the itemset item node,
  *   referencing a form's `itext` translations, etc).
  */
-export const createSelectItems = (selectField: SelectField): Accessor<readonly SelectItem[]> => {
-	const { items, itemset } = selectField.definition.bodyElement;
+export const createItemCollection = (control: ItemCollectionControl): Accessor<readonly Item[]> => {
+	const { items, itemset } = control.definition.bodyElement;
 
-	if (itemset == null) {
-		return createTranslatedStaticSelectItems(selectField, items);
+	if (itemset != null) {
+		return createItemset(control, itemset);
 	}
 
-	return createItemset(selectField, itemset);
+	return createTranslatedStaticItems(control, items);
 };

package/src/lib/xml-serialization.ts

@@ -1,3 +1,6 @@
+import type { NamespaceDeclarationMap } from './names/NamespaceDeclarationMap.ts';
+import type { QualifiedName } from './names/QualifiedName.ts';
+
 declare const ESCAPED_XML_TEXT_BRAND: unique symbol;
 
 export type EscapedXMLText = string & { readonly [ESCAPED_XML_TEXT_BRAND]: true };
@@ -75,22 +78,86 @@ export const escapeXMLText = <Text extends string>(
 		: (out as EscapedXMLText);
 };
 
-const serializeElementXML = (nodeName: string, children: string): string => {
+interface SerializableElementAttribute {
+	serializeAttributeXML(): string;
+}
+
+interface ElementXMLSerializationOptions {
+	readonly namespaceDeclarations?: NamespaceDeclarationMap;
+	readonly attributes?: readonly SerializableElementAttribute[];
+}
+
+const serializeElementNamespaceDeclarationXML = (
+	namespaceDeclarations?: NamespaceDeclarationMap
+): string => {
+	if (namespaceDeclarations == null) {
+		return '';
+	}
+
+	return Array.from(namespaceDeclarations.values())
+		.map((namespaceDeclaration) => {
+			return namespaceDeclaration.serializeNamespaceDeclarationXML({
+				omitDefaultNamespace: true,
+			});
+		})
+		.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 = {}
+): string => {
+	// See JSDoc for the `getPrefixedName` method. If we find we do actually need
+	// custom element (subtree) prefix resolution, we'd uncomment the argument
+	// below. (Either way, at time of writing the affected tests pass where
+	// expected when the option is passed. It's omitted on the presumption that it
+	// would be redundant, since the nodes being serialized are already resolved
+	// with the same set of namespace declarations which would affect them.)
+	//
+	// prettier-ignore
+	const nodeName = qualifiedName.getPrefixedName(
+		// options.namespaceDeclarations
+	);
+	const namespaceDeclarations = serializeElementNamespaceDeclarationXML(
+		options.namespaceDeclarations
+	);
+	const attributes = serializeElementAttributeXML(options.attributes);
+	const prefix = `<${nodeName}${namespaceDeclarations}${attributes}`;
+
 	if (children === '') {
-		return `<${nodeName}/>`;
+		return `${prefix}/>`;
 	}
 
-	// TODO: attributes
-	return `<${nodeName}>${children}</${nodeName}>`;
+	return `${prefix}>${children}</${nodeName}>`;
 };
 
 export const serializeParentElementXML = (
-	nodeName: string,
-	serializedChildren: readonly string[]
+	qualifiedName: QualifiedName,
+	serializedChildren: readonly string[],
+	options?: ElementXMLSerializationOptions
 ): string => {
-	return serializeElementXML(nodeName, serializedChildren.join(''));
+	return serializeElementXML(qualifiedName, serializedChildren.join(''), options);
 };
 
-export const serializeLeafElementXML = (nodeName: string, xmlValue: EscapedXMLText): string => {
-	return serializeElementXML(nodeName, xmlValue.normalize());
+export const serializeLeafElementXML = (
+	qualifiedName: QualifiedName,
+	xmlValue: EscapedXMLText,
+	options?: ElementXMLSerializationOptions
+): string => {
+	return serializeElementXML(qualifiedName, xmlValue.normalize(), options);
 };