@getodk/xforms-engine 0.16.0 → 0.17.0

package/src/instance/UploadControl.ts

@@ -9,7 +9,10 @@ import { UploadValueTypeError } from '../error/UploadValueTypeError.ts';
 import type { XFormsXPathElement } from '../integration/xpath/adapter/XFormsXPathNode.ts';
 import type { StaticLeafElement } from '../integration/xpath/static-dom/StaticElement.ts';
 import { createValueNodeInstanceState } from '../lib/client-reactivity/instance-state/createValueNodeInstanceState.ts';
-import { createAttributeState } from '../lib/reactivity/createAttributeState.ts';
+import {
+	createAttributeState,
+	type AttributeState,
+} from '../lib/reactivity/createAttributeState.ts';
 import { createInstanceAttachment } from '../lib/reactivity/createInstanceAttachment.ts';
 import type { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
 import type { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
@@ -29,6 +32,7 @@ import type {
 	InstanceAttachment,
 	InstanceAttachmentRuntimeValue,
 } from './attachments/InstanceAttachment.ts';
+import { buildAttributes } from './attachments/buildAttributes.ts';
 import type { GeneralParentNode } from './hierarchy.ts';
 import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
 import type { InstanceAttachmentContext } from './internal-api/InstanceAttachmentContext.ts';
@@ -106,6 +110,7 @@ export class UploadControl
 	// InstanceNode
 	protected readonly state: SharedNodeState<UploadControlStateSpec>;
 	protected readonly engineState: EngineState<UploadControlStateSpec>;
+	readonly attributeState: AttributeState;
 
 	// InstanceValueContext
 	readonly decodeInstanceValue: DecodeInstanceValue;
@@ -136,7 +141,7 @@ export class UploadControl
 		const instanceAttachment = createInstanceAttachment(this);
 
 		this.instanceAttachment = instanceAttachment;
-		const attributeState = createAttributeState(this.scope);
+		this.attributeState = createAttributeState(this.scope);
 		this.decodeInstanceValue = instanceAttachment.decodeInstanceValue;
 		this.getXPathValue = instanceAttachment.getInstanceValue;
 
@@ -153,7 +158,7 @@ export class UploadControl
 				children: null,
 				valueOptions: null,
 				value: instanceAttachment.valueState,
-				attributes: attributeState.getAttributes,
+				attributes: this.attributeState.getAttributes,
 				instanceValue: instanceAttachment.getInstanceValue,
 			},
 			this.instanceConfig
@@ -163,6 +168,7 @@ export class UploadControl
 		this.engineState = state.engineState;
 		this.currentState = state.currentState;
 		this.validation = createValidationState(this, this.instanceConfig);
+		this.attributeState.setAttributes(buildAttributes(this));
 		this.instanceState = createValueNodeInstanceState(this);
 	}
 
@@ -180,6 +186,10 @@ export class UploadControl
 		return [];
 	}
 
+	override getAttributes(): readonly Attribute[] {
+		return this.attributeState.getAttributes();
+	}
+
 	// UploadNode
 	setValue(value: InstanceAttachmentRuntimeValue): Root {
 		this.instanceAttachment.setValue(value);

package/src/instance/abstract/DescendantNode.ts

@@ -11,12 +11,13 @@ import type {
 } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
 import { XFORMS_XPATH_NODE_RANGE_KIND } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
 import type { EngineXPathEvaluator } from '../../integration/xpath/EngineXPathEvaluator.ts';
+import type { StaticAttribute } from '../../integration/xpath/static-dom/StaticAttribute.ts';
 import type { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
 import { createComputedExpression } from '../../lib/reactivity/createComputedExpression.ts';
 import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
 import type { AnyNodeDefinition } from '../../parse/model/NodeDefinition.ts';
 import type { DescendantNodeInitOptions } from '../children/DescendantNodeInitOptions.ts';
-import type { AnyChildNode, AnyParentNode, RepeatRange } from '../hierarchy.ts';
+import type { AnyChildNode, AnyNode, RepeatRange } from '../hierarchy.ts';
 import type { EvaluationContext } from '../internal-api/EvaluationContext.ts';
 import type { RepeatInstance } from '../repeat/RepeatInstance.ts';
 import type { Root } from '../Root.ts';
@@ -63,7 +64,7 @@ export abstract class DescendantNode<
 		Definition extends DescendantNodeDefinition,
 		// eslint-disable-next-line @typescript-eslint/no-explicit-any
 		Spec extends DescendantNodeStateSpec<any>,
-		Parent extends AnyParentNode,
+		Parent extends AnyNode,
 		Child extends AnyChildNode | null = null,
 	>
 	extends InstanceNode<Definition, Spec, Parent, Child>
@@ -137,7 +138,7 @@ export abstract class DescendantNode<
 
 	constructor(
 		override readonly parent: Parent,
-		override readonly instanceNode: StaticElement | null,
+		override readonly instanceNode: StaticAttribute | StaticElement | null,
 		override readonly definition: Definition,
 		options?: DescendantNodeOptions
 	) {

package/src/instance/abstract/InstanceNode.ts

@@ -28,7 +28,7 @@ import type { AnyNodeDefinition } from '../../parse/model/NodeDefinition.ts';
 import type { Attribute } from '../Attribute.ts';
 import type { PrimaryInstance } from '../PrimaryInstance.ts';
 import type { Root } from '../Root.ts';
-import type { AnyChildNode, AnyNode, AnyParentNode } from '../hierarchy.ts';
+import type { AnyChildNode, AnyNode } from '../hierarchy.ts';
 import { nodeID } from '../identity.ts';
 import type { EvaluationContext } from '../internal-api/EvaluationContext.ts';
 import type { InstanceConfig } from '../internal-api/InstanceConfig.ts';
@@ -84,7 +84,7 @@ export type InstanceNodeCurrentState<
 		};
 
 interface ComputableReferenceNode {
-	readonly parent: AnyParentNode | null;
+	readonly parent: AnyNode | null;
 	readonly definition: AnyNodeDefinition;
 }
 
@@ -103,7 +103,7 @@ export abstract class InstanceNode<
 		Definition extends AnyNodeDefinition,
 		// eslint-disable-next-line @typescript-eslint/no-explicit-any
 		Spec extends InstanceNodeStateSpec<any>,
-		Parent extends AnyParentNode | null,
+		Parent extends AnyNode | null,
 		Child extends AnyChildNode | null = null,
 	>
 	implements BaseEngineNode, XFormsXPathPrimaryInstanceNode, EvaluationContext
@@ -272,4 +272,6 @@ export abstract class InstanceNode<
 			.map((child) => child.getXPathValue())
 			.join('');
 	}
+
+	abstract getAttributes(): readonly Attribute[];
 }

package/src/instance/attachments/buildAttributes.ts

@@ -1,3 +1,6 @@
+import type { StaticAttribute } from '../../integration/xpath/static-dom/StaticAttribute.ts';
+import type { StaticDocument } from '../../integration/xpath/static-dom/StaticDocument.ts';
+import type { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
 import { Attribute } from '../Attribute';
 import type { AnyNode } from '../hierarchy.ts';
 import type { InputControl } from '../InputControl.ts';
@@ -5,11 +8,32 @@ import type { ModelValue } from '../ModelValue.ts';
 import type { Note } from '../Note.ts';
 import type { RangeControl } from '../RangeControl.ts';
 
+function buildInstanceAttributeMap(
+	instanceNode: StaticAttribute | StaticDocument | StaticElement | null
+): Map<string, StaticAttribute> {
+	const map = new Map<string, StaticAttribute>();
+	if (!instanceNode) {
+		return map;
+	}
+	for (const attribute of instanceNode.attributes) {
+		map.set(attribute.qualifiedName.getPrefixedName(), attribute);
+	}
+	return map;
+}
+
 export function buildAttributes(
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	owner: AnyNode | InputControl<any> | ModelValue<any> | Note<any> | RangeControl<any>
 ): Attribute[] {
-	return Array.from(owner.definition.attributes.values()).map((attributeDefinition) => {
-		return new Attribute(owner, attributeDefinition, attributeDefinition.template);
+	const attributes = owner.definition.attributes;
+	if (!attributes) {
+		return [];
+	}
+	const instanceAttributes = buildInstanceAttributeMap(owner.instanceNode);
+	return Array.from(attributes.values()).map((attributeDefinition) => {
+		const instanceNode =
+			instanceAttributes.get(attributeDefinition.qualifiedName.getPrefixedName()) ??
+			attributeDefinition.template;
+		return new Attribute(owner, attributeDefinition, instanceNode);
 	});
 }

package/src/instance/children/childrenInitOptions.ts

@@ -1,3 +1,4 @@
+import type { StaticAttribute } from '../../integration/xpath/static-dom/StaticAttribute.ts';
 import type { StaticDocument } from '../../integration/xpath/static-dom/StaticDocument.ts';
 import type { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
 import type { ModelDefinition } from '../../parse/model/ModelDefinition.ts';
@@ -37,7 +38,7 @@ const collectModelChildNodesets = (parentTemplate: StaticElement): readonly stri
 type InstanceNodesByNodeset = ReadonlyMap<string, readonly [StaticElement, ...StaticElement[]]>;
 
 const groupChildElementsByNodeset = (
-	parent: StaticDocument | StaticElement
+	parent: StaticAttribute | StaticDocument | StaticElement
 ): InstanceNodesByNodeset => {
 	const result = new Map<string, [StaticElement, ...StaticElement[]]>();
 

package/src/instance/hierarchy.ts

@@ -1,3 +1,4 @@
+import type { Attribute } from './Attribute.ts';
 import type { Group } from './Group.ts';
 import type { AnyInputControl } from './InputControl.ts';
 import type { AnyModelValue } from './ModelValue.ts';
@@ -23,6 +24,7 @@ export type AnyNode =
 	| Group
 	| RepeatRange
 	| RepeatInstance
+	| Attribute
 	| AnyNote
 	| AnyModelValue
 	| AnyInputControl

package/src/instance/internal-api/AttributeContext.ts

@@ -11,6 +11,7 @@ import type { InstanceConfig } from './InstanceConfig.ts';
 export interface InstanceAttributeContextDocument {
 	readonly initializationMode: FormInstanceInitializationMode;
 	readonly isAttached: Accessor<boolean>;
+	getBackgroundGeopoint: Accessor<Promise<string>>;
 }
 
 export type DecodeInstanceValue = (value: string) => string;

package/src/instance/internal-api/InstanceConfig.ts

@@ -1,6 +1,7 @@
 import type { InstanceAttachmentFileNameFactory } from '../../client/attachments/InstanceAttachmentsConfig.ts';
 import type {
 	FormInstanceConfig,
+	GeolocationProvider,
 	PreloadProperties,
 } from '../../client/form/FormInstanceConfig.ts';
 import type { OpaqueReactiveObjectFactory } from '../../client/OpaqueReactiveObjectFactory.ts';
@@ -14,4 +15,6 @@ export interface InstanceConfig {
 	readonly computeAttachmentName: InstanceAttachmentFileNameFactory;
 
 	readonly preloadProperties: PreloadProperties;
+
+	readonly geolocationProvider: GeolocationProvider | undefined;
 }

package/src/instance/internal-api/InstanceValueContext.ts

@@ -11,6 +11,7 @@ import type { InstanceConfig } from './InstanceConfig.ts';
 export interface InstanceValueContextDocument {
 	readonly initializationMode: FormInstanceInitializationMode;
 	readonly isAttached: Accessor<boolean>;
+	getBackgroundGeopoint: Accessor<Promise<string>>;
 }
 
 export type DecodeInstanceValue = (value: string) => string;

package/src/instance/markdown/MarkdownNode.ts

@@ -2,18 +2,26 @@ import {
 	type AnchorMarkdownNode,
 	type ChildMarkdownNode as ClientChildMarkdownNode,
 	type HtmlMarkdownNode as ClientHtmlMarkdownNode,
+	type MarkdownNode as ClientMarkdownNode,
 	type ParentMarkdownNode as ClientParentMarkdownNode,
 	type StyledMarkdownNode as ClientStyledMarkdownNode,
 	type ElementName,
-	type MarkdownNode,
 	type MarkdownProperty,
 } from '../../client';
 
-abstract class ParentMarkdownNode implements ClientParentMarkdownNode {
+abstract class MarkdownNode {
+	readonly id: string;
+	constructor() {
+		this.id = crypto.randomUUID();
+	}
+}
+
+abstract class ParentMarkdownNode extends MarkdownNode implements ClientParentMarkdownNode {
 	readonly children;
 	readonly role = 'parent';
 	abstract elementName: ElementName;
-	constructor(children: MarkdownNode[]) {
+	constructor(children: ClientMarkdownNode[]) {
+		super();
 		this.children = children;
 	}
 }
@@ -69,18 +77,20 @@ export class ListItem extends ParentMarkdownNode {
 export class Anchor extends ParentMarkdownNode implements AnchorMarkdownNode {
 	readonly elementName = 'a';
 	readonly url: string;
-	constructor(children: MarkdownNode[], url: string) {
+	constructor(children: ClientMarkdownNode[], url: string) {
 		super(children);
 		this.url = url;
 	}
 }
 
 abstract class StyledMarkdownNode implements ClientParentMarkdownNode {
+	readonly id: string;
 	readonly children;
 	readonly role = 'parent';
 	abstract elementName: ElementName;
 	readonly properties: MarkdownProperty | undefined;
-	constructor(children: MarkdownNode[], properties: MarkdownProperty | undefined) {
+	constructor(children: ClientMarkdownNode[], properties: MarkdownProperty | undefined) {
+		this.id = crypto.randomUUID();
 		this.children = children;
 		this.properties = properties;
 	}
@@ -98,18 +108,20 @@ export class Div extends StyledMarkdownNode implements ClientStyledMarkdownNode
 	readonly elementName = 'div';
 }
 
-export class ChildMarkdownNode implements ClientChildMarkdownNode {
+export class ChildMarkdownNode extends MarkdownNode implements ClientChildMarkdownNode {
 	readonly role = 'child';
 	readonly value: string;
 	constructor(value: string) {
+		super();
 		this.value = value;
 	}
 }
 
-export class Html implements ClientHtmlMarkdownNode {
+export class Html extends MarkdownNode implements ClientHtmlMarkdownNode {
 	readonly role = 'html';
 	readonly unsafeHtml: string;
 	constructor(unsafeHtml: string) {
+		super();
 		this.unsafeHtml = unsafeHtml;
 	}
 }

package/src/instance/repeat/RepeatInstance.ts

@@ -13,7 +13,10 @@ import type { AncestorNodeValidationState } from '../../client/validation.ts';
 import type { XFormsXPathElement } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
 import type { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
 import { createTemplatedNodeInstanceState } from '../../lib/client-reactivity/instance-state/createTemplatedNodeInstanceState.ts';
-import { createAttributeState } from '../../lib/reactivity/createAttributeState.ts';
+import {
+	createAttributeState,
+	type AttributeState,
+} from '../../lib/reactivity/createAttributeState.ts';
 import type { ChildrenState } from '../../lib/reactivity/createChildrenState.ts';
 import { createChildrenState } from '../../lib/reactivity/createChildrenState.ts';
 import type { MaterializedChildren } from '../../lib/reactivity/materializeCurrentStateChildren.ts';
@@ -60,6 +63,7 @@ export class RepeatInstance
 		ClientReactiveSerializableTemplatedNode
 {
 	private readonly childrenState: ChildrenState<GeneralChildNode>;
+	private readonly attributeState: AttributeState;
 	private readonly currentIndex: Accessor<number>;
 
 	override readonly [XPathNodeKindKey] = 'element';
@@ -131,7 +135,7 @@ export class RepeatInstance
 		this.appearances = definition.bodyElement.appearances;
 
 		const childrenState = createChildrenState<RepeatInstance, GeneralChildNode>(this);
-		const attributeState = createAttributeState(this.scope);
+		this.attributeState = createAttributeState(this.scope);
 
 		this.childrenState = childrenState;
 		this.currentIndex = currentIndex;
@@ -147,7 +151,7 @@ export class RepeatInstance
 				// TODO: only-child <group><label>
 				label: createNodeLabel(this, definition),
 				hint: null,
-				attributes: attributeState.getAttributes,
+				attributes: this.attributeState.getAttributes,
 				children: childrenState.childIds,
 				valueOptions: null,
 				value: null,
@@ -192,4 +196,8 @@ export class RepeatInstance
 	getChildren(): readonly GeneralChildNode[] {
 		return this.childrenState.getChildren();
 	}
+
+	override getAttributes(): readonly Attribute[] {
+		return this.attributeState.getAttributes();
+	}
 }

package/src/instance/text/markdownFormat.ts

@@ -42,7 +42,7 @@ const SUPPORTED_HTML_TAGS = Object.entries(HTML_TAG_MAP).map(([tag, type]) => {
 	};
 });
 
-let outputStrings: Map<string, string>;
+const outputStrings = new Map<string, string>();
 
 function validateStyleProperty(name: string | undefined, value: string | undefined): boolean {
 	if (!name || !value) {
@@ -208,7 +208,8 @@ function toOdkMarkdown(str: string): MarkdownNode[] {
 }
 
 export function format(chunks: readonly TextChunk[]): MarkdownNode[] {
-	outputStrings = new Map<string, string>();
 	const str = escapeEditableChunks(chunks);
-	return toOdkMarkdown(str);
+	const result = toOdkMarkdown(str);
+	outputStrings.clear();
+	return result;
 }

package/src/integration/xpath/adapter/XFormsXPathNode.ts

@@ -120,6 +120,7 @@ export interface XFormsXPathPrimaryInstanceNode extends XFormsXPathNode {
 // prettier-ignore
 export type XFormsXPathPrimaryInstanceDescendantNodeKind =
 	| XFormsXPathNodeRangeKind
+	| XPathAttributeKind
 	| XPathElementKind
 	| XPathTextKind;
 

package/src/integration/xpath/adapter/engineDOMAdapter.ts

@@ -10,10 +10,10 @@ import {
 } from './names.ts';
 import {
 	compareDocumentOrder,
+	getAttributes,
 	getChildElements,
 	getChildNodes,
 	getContainingEngineXPathDocument,
-	getEngineXPathAttributes,
 	getNamespaceDeclarations,
 	getNextSiblingElement,
 	getNextSiblingNode,
@@ -43,7 +43,7 @@ export const engineDOMAdapter: EngineDOMAdapter = {
 
 	// XPathTraversalAdapter
 	compareDocumentOrder,
-	getAttributes: getEngineXPathAttributes,
+	getAttributes: getAttributes,
 	getChildElements: getChildElements,
 	getChildNodes: getChildNodes,
 	getContainingDocument: getContainingEngineXPathDocument,

package/src/integration/xpath/adapter/kind.ts

@@ -1,5 +1,6 @@
 import type { XPathNodeKind } from '@getodk/xpath';
 import { XPathNodeKindKey } from '@getodk/xpath';
+import type { Attribute } from '../../../instance/Attribute.ts';
 import type { AnyChildNode, AnyNode, AnyParentNode } from '../../../instance/hierarchy.ts';
 import type { PrimaryInstance } from '../../../instance/PrimaryInstance.ts';
 import type { StaticAttribute } from '../static-dom/StaticAttribute.ts';
@@ -7,6 +8,7 @@ import type { StaticDocument } from '../static-dom/StaticDocument.ts';
 import type { StaticElement } from '../static-dom/StaticElement.ts';
 import type { StaticText } from '../static-dom/StaticText.ts';
 import type {
+	XFormsXPathAttribute,
 	XFormsXPathComment,
 	XFormsXPathDocument,
 	XFormsXPathElement,
@@ -17,12 +19,15 @@ export type PrimaryInstanceXPathNode = Extract<AnyNode, XFormsXPathPrimaryInstan
 
 export type PrimaryInstanceXPathElement = Extract<AnyChildNode, XFormsXPathElement>;
 
+export type PrimaryInstanceXPathAttribute = Extract<Attribute, XFormsXPathAttribute>;
+
 export type PrimaryInstanceXPathComment = Extract<AnyChildNode, XFormsXPathComment>;
 
 // prettier-ignore
 export type PrimaryInstanceXPathChildNode =
 	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
 	| PrimaryInstanceXPathElement
+	| PrimaryInstanceXPathAttribute
 	| PrimaryInstanceXPathComment;
 
 // prettier-ignore
@@ -41,7 +46,7 @@ export type EngineXPathComment =
 
 // Giving this a type alias anticipates eventually implementing attributes
 // in primary instance state as well
-export type EngineXPathAttribute = StaticAttribute;
+export type EngineXPathAttribute = PrimaryInstanceXPathAttribute | StaticAttribute;
 
 export type EngineXPathText = StaticText;
 

package/src/integration/xpath/adapter/names.ts

@@ -128,6 +128,7 @@ export const resolveEngineXPathNodeNamespaceURI = (
 		case 'static-text':
 			return resolveNamespaceURIFromStaticNodeContext(node, prefix);
 
+		case 'attribute':
 		case 'group':
 		case 'input':
 		case 'model-value':

package/src/integration/xpath/adapter/traversal.ts

@@ -8,7 +8,6 @@ import type {
 	EngineXPathDocument,
 	EngineXPathElement,
 	EngineXPathNode,
-	EngineXPathParentNode,
 	PrimaryInstanceXPathChildNode,
 	XFormsXPathChildNode,
 } from './kind.ts';
@@ -18,13 +17,13 @@ export const getContainingEngineXPathDocument = (node: EngineXPathNode): EngineX
 	return node.rootDocument;
 };
 
-export const getEngineXPathAttributes = (
-	node: EngineXPathNode
-): readonly EngineXPathAttribute[] => {
+export const getAttributes = (node: EngineXPathNode): readonly EngineXPathAttribute[] => {
 	if (node.nodeType === 'static-element') {
 		return node.attributes;
 	}
-
+	if (isEngineXPathElement(node)) {
+		return node.getAttributes();
+	}
 	return [];
 };
 
@@ -43,7 +42,7 @@ export const getEngineXPathAttributes = (
  */
 export const getNamespaceDeclarations = (): readonly [] => [];
 
-export const getParentNode = (node: EngineXPathNode): EngineXPathParentNode | null => {
+export const getParentNode = (node: EngineXPathNode): EngineXPathNode | null => {
 	if (node.nodeType === 'repeat-instance') {
 		return node.parent.parent;
 	}

package/src/integration/xpath/static-dom/StaticAttribute.ts

@@ -20,6 +20,7 @@ export class StaticAttribute extends StaticNode<'attribute'> implements XFormsXP
 	readonly nodeset: string;
 	readonly attributes = [] as const;
 	readonly children = null;
+	readonly childElements = [];
 	readonly value: string;
 
 	constructor(

package/src/integration/xpath/static-dom/StaticDocument.ts

@@ -1,4 +1,5 @@
 import type { XFormsXPathDocument } from '../adapter/XFormsXPathNode.ts';
+import type { StaticAttribute } from './StaticAttribute.ts';
 import type { StaticElementOptions } from './StaticElement.ts';
 import { StaticElement } from './StaticElement.ts';
 import { StaticParentNode } from './StaticParentNode.ts';
@@ -15,6 +16,7 @@ export class StaticDocument extends StaticParentNode<'document'> implements XFor
 	readonly nodeset: string;
 	readonly children: readonly [root: StaticElement];
 	readonly childElements: readonly [root: StaticElement];
+	readonly attributes: readonly StaticAttribute[] = [];
 
 	constructor(options: StaticDocumentOptions) {
 		super('document');

package/src/lib/codecs/{Geopoint/Geopoint.ts → geolocation/Geolocation.ts}

@@ -1,8 +1,3 @@
-/**
- * This abstract class defines the minimal behavior for a default geopoint.
- * It can be expanded later to support units (e.g., degrees or meters),
- * which would also serve as documentation to clarify what each value represents.
- */
 abstract class SemanticValue<Semantic extends string, Value extends number | null> {
 	abstract readonly semantic: Semantic;
 
@@ -25,26 +20,21 @@ class Accuracy<Value extends number | null = number> extends SemanticValue<'accu
 	readonly semantic = 'accuracy';
 }
 
-export interface GeopointValue {
+export interface LocationPoint {
 	readonly latitude: number;
 	readonly longitude: number;
 	readonly altitude: number | null;
 	readonly accuracy: number | null;
 }
 
-export type GeopointRuntimeValue = GeopointValue | null;
-
-// TODO: Add support for GeoJSONValue
-export type GeopointInputValue = GeopointRuntimeValue | string;
-
-interface GeopointInternalValue {
+interface GeolocationInternalValue {
 	readonly latitude: Latitude;
 	readonly longitude: Longitude;
 	readonly altitude: Altitude<null> | Altitude<number>;
 	readonly accuracy: Accuracy<null> | Accuracy<number>;
 }
 
-type GeopointTuple =
+type LocationPointTuple =
 	| readonly [
 			latitude: Latitude,
 			longitude: Longitude,
@@ -54,6 +44,8 @@ type GeopointTuple =
 	| readonly [latitude: Latitude, longitude: Longitude, altitude: Altitude]
 	| readonly [latitude: Latitude, longitude: Longitude];
 
+export const SEGMENT_SEPARATOR = ';';
+
 const DEGREES_MAX = {
 	latitude: 90,
 	longitude: 180,
@@ -61,10 +53,10 @@ const DEGREES_MAX = {
 
 type CoordinateType = keyof typeof DEGREES_MAX;
 
-export class Geopoint {
-	private readonly internalValue: GeopointInternalValue;
+export class Geolocation {
+	private readonly internalValue: GeolocationInternalValue;
 
-	constructor(coordinates: GeopointValue) {
+	constructor(coordinates: LocationPoint) {
 		const { latitude, longitude, altitude, accuracy } = coordinates;
 
 		this.internalValue = {
@@ -75,7 +67,7 @@ export class Geopoint {
 		};
 	}
 
-	getTuple(): GeopointTuple {
+	getTuple(): LocationPointTuple {
 		const { latitude, longitude, altitude, accuracy } = this.internalValue;
 
 		if (accuracy.value != null) {
@@ -89,12 +81,16 @@ export class Geopoint {
 		return [latitude, longitude];
 	}
 
-	getRuntimeValue(): GeopointRuntimeValue {
+	getRuntimeValue(): LocationPoint | null {
 		const { latitude, longitude, altitude, accuracy } = this.internalValue;
 		const isLatitude = this.isValidDegrees('latitude', latitude.value);
 		const isLongitude = this.isValidDegrees('longitude', longitude.value);
 
-		if (!isLatitude || !isLongitude || Geopoint.isNullLocation(latitude.value, longitude.value)) {
+		if (
+			!isLatitude ||
+			!isLongitude ||
+			Geolocation.isNullLocation(latitude.value, longitude.value)
+		) {
 			return null;
 		}
 
@@ -118,8 +114,9 @@ export class Geopoint {
 		return latitude === 0 && longitude === 0;
 	}
 
-	static parseString(value: string): GeopointRuntimeValue {
-		if (value.trim() === '') {
+	static parseString(value: string): LocationPoint | null {
+		value = value.trim();
+		if (value === '') {
 			return null;
 		}
 
@@ -132,12 +129,12 @@ export class Geopoint {
 		return new this({ latitude, longitude, altitude, accuracy }).getRuntimeValue();
 	}
 
-	static toCoordinatesString(value: GeopointInputValue): string {
-		const decodedValue = typeof value === 'string' ? Geopoint.parseString(value) : value;
+	static toCoordinatesString(value: LocationPoint | string | null): string {
+		const decodedValue = typeof value === 'string' ? Geolocation.parseString(value) : value;
 
 		if (
 			decodedValue == null ||
-			Geopoint.isNullLocation(decodedValue.latitude, decodedValue.longitude)
+			Geolocation.isNullLocation(decodedValue.latitude, decodedValue.longitude)
 		) {
 			return '';
 		}
@@ -147,4 +144,26 @@ export class Geopoint {
 			.map((item) => item.value ?? 0)
 			.join(' ');
 	}
+
+	static isClosedShape(points: LocationPoint[]) {
+		const firstPoint = points[0];
+		const lastPoint = points[points.length - 1];
+		return (
+			firstPoint?.latitude === lastPoint?.latitude && firstPoint?.longitude === lastPoint?.longitude
+		);
+	}
+
+	static getSegments(value: string): string[] | null {
+		if (value.trim() === '') {
+			return null;
+		}
+
+		const parts = value.split(SEGMENT_SEPARATOR);
+		// Handles trailing semicolon, which is valid and common in ODK.
+		if (parts[parts.length - 1]?.trim() === '') {
+			parts.pop();
+		}
+
+		return parts;
+	}
 }