@getodk/xforms-engine 0.5.0 → 0.6.0

package/src/lib/codecs/Geopoint/Geopoint.ts

@@ -0,0 +1,150 @@
+/**
+ * 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;
+
+	constructor(readonly value: Value) {}
+}
+
+class Latitude extends SemanticValue<'latitude', number> {
+	readonly semantic = 'latitude';
+}
+
+class Longitude extends SemanticValue<'longitude', number> {
+	readonly semantic = 'longitude';
+}
+
+class Altitude<Value extends number | null = number> extends SemanticValue<'altitude', Value> {
+	readonly semantic = 'altitude';
+}
+
+class Accuracy<Value extends number | null = number> extends SemanticValue<'accuracy', Value> {
+	readonly semantic = 'accuracy';
+}
+
+export interface GeopointValue {
+	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 {
+	readonly latitude: Latitude;
+	readonly longitude: Longitude;
+	readonly altitude: Altitude<null> | Altitude<number>;
+	readonly accuracy: Accuracy<null> | Accuracy<number>;
+}
+
+type GeopointTuple =
+	| readonly [
+			latitude: Latitude,
+			longitude: Longitude,
+			altitude: Altitude<null> | Altitude<number>,
+			accuracy: Accuracy,
+	  ]
+	| readonly [latitude: Latitude, longitude: Longitude, altitude: Altitude]
+	| readonly [latitude: Latitude, longitude: Longitude];
+
+const DEGREES_MAX = {
+	latitude: 90,
+	longitude: 180,
+} as const;
+
+type CoordinateType = keyof typeof DEGREES_MAX;
+
+export class Geopoint {
+	private readonly internalValue: GeopointInternalValue;
+
+	constructor(coordinates: GeopointValue) {
+		const { latitude, longitude, altitude, accuracy } = coordinates;
+
+		this.internalValue = {
+			latitude: new Latitude(latitude),
+			longitude: new Longitude(longitude),
+			altitude: this.isValidNumber(altitude) ? new Altitude(altitude) : new Altitude(null),
+			accuracy: this.isValidNumber(accuracy) ? new Accuracy(accuracy) : new Accuracy(null),
+		};
+	}
+
+	getTuple(): GeopointTuple {
+		const { latitude, longitude, altitude, accuracy } = this.internalValue;
+
+		if (accuracy.value != null) {
+			return [latitude, longitude, altitude, accuracy];
+		}
+
+		if (altitude.value != null) {
+			return [latitude, longitude, altitude];
+		}
+
+		return [latitude, longitude];
+	}
+
+	getRuntimeValue(): GeopointRuntimeValue {
+		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)) {
+			return null;
+		}
+
+		return {
+			latitude: latitude.value,
+			longitude: longitude.value,
+			altitude: altitude.value,
+			accuracy: accuracy.value,
+		};
+	}
+
+	private isValidDegrees(coordinate: CoordinateType, degrees: number): degrees is number {
+		return this.isValidNumber(degrees) && Math.abs(degrees) <= DEGREES_MAX[coordinate];
+	}
+
+	private isValidNumber(value: number | null | undefined) {
+		return value != null && !Number.isNaN(value);
+	}
+
+	private static isNullLocation(latitude: number, longitude: number) {
+		return latitude === 0 && longitude === 0;
+	}
+
+	static parseString(value: string): GeopointRuntimeValue {
+		if (value.trim() === '') {
+			return null;
+		}
+
+		const [latitude, longitude, altitude = null, accuracy = null] = value.split(/\s+/).map(Number);
+
+		if (latitude == null || longitude == null || Number.isNaN(altitude) || Number.isNaN(accuracy)) {
+			return null;
+		}
+
+		return new this({ latitude, longitude, altitude, accuracy }).getRuntimeValue();
+	}
+
+	static toCoordinatesString(value: GeopointInputValue): string {
+		const decodedValue = typeof value === 'string' ? Geopoint.parseString(value) : value;
+
+		if (
+			decodedValue == null ||
+			Geopoint.isNullLocation(decodedValue.latitude, decodedValue.longitude)
+		) {
+			return '';
+		}
+
+		return new this(decodedValue)
+			.getTuple()
+			.map((item) => item.value ?? 0)
+			.join(' ');
+	}
+}

package/src/lib/codecs/Geopoint/GeopointValueCodec.ts

@@ -0,0 +1,20 @@
+import { type CodecDecoder, type CodecEncoder, ValueCodec } from '../ValueCodec.ts';
+import { Geopoint, type GeopointInputValue, type GeopointRuntimeValue } from './Geopoint.ts';
+
+export class GeopointValueCodec extends ValueCodec<
+	'geopoint',
+	GeopointRuntimeValue,
+	GeopointInputValue
+> {
+	constructor() {
+		const encodeValue: CodecEncoder<GeopointInputValue> = (value) => {
+			return Geopoint.toCoordinatesString(value);
+		};
+
+		const decodeValue: CodecDecoder<GeopointRuntimeValue> = (value: string) => {
+			return Geopoint.parseString(value);
+		};
+
+		super('geopoint', encodeValue, decodeValue);
+	}
+}

package/src/lib/codecs/NoteCodec.ts

@@ -0,0 +1,32 @@
+import type { ValueType } from '../../client/ValueType.ts';
+import type { RuntimeInputValue, RuntimeValue, SharedValueCodec } from './getSharedValueCodec.ts';
+import { ValueCodec } from './ValueCodec.ts';
+
+// prettier-ignore
+export type NoteRuntimeValue<V extends ValueType> =
+	| RuntimeValue<V>
+	| null;
+
+// prettier-ignore
+export type NoteInputValue<V extends ValueType> =
+	| RuntimeInputValue<V>
+	| RuntimeValue<V>
+	| null;
+
+export class NoteCodec<V extends ValueType> extends ValueCodec<
+	V,
+	NoteRuntimeValue<V>,
+	NoteInputValue<V>
+> {
+	constructor(baseCodec: SharedValueCodec<V>) {
+		const encodeValue = (value: NoteInputValue<V>): string => {
+			return baseCodec.encodeValue(value ?? '');
+		};
+
+		const decodeValue = (value: string): NoteRuntimeValue<V> => {
+			return value === '' ? null : baseCodec.decodeValue(value);
+		};
+
+		super(baseCodec.valueType, encodeValue, decodeValue);
+	}
+}

package/src/lib/codecs/RangeCodec.ts

@@ -0,0 +1,65 @@
+import type { RangeValue } from '../../client/RangeNode.ts';
+import { ValueTypeInvariantError } from '../../error/ValueTypeInvariantError.ts';
+import type { RangeNodeDefinition, RangeValueType } from '../../parse/model/RangeNodeDefinition.ts';
+import type { RuntimeInputValue, RuntimeValue, SharedValueCodec } from './getSharedValueCodec.ts';
+import { ValueCodec } from './ValueCodec.ts';
+
+export type RangeRuntimeValue<V extends RangeValueType> = RuntimeValue<V>;
+
+export type RangeInputValue<V extends RangeValueType> = RuntimeInputValue<V>;
+
+export class RangeCodec<V extends RangeValueType> extends ValueCodec<
+	V,
+	RangeRuntimeValue<V>,
+	RangeInputValue<V>
+> {
+	constructor(baseCodec: SharedValueCodec<V>, definition: RangeNodeDefinition<V>) {
+		const { valueType, bounds } = definition;
+		const { min, max } = bounds;
+
+		type ComparableRangeValue = bigint | number | null;
+
+		const toComparableValue = (value: RangeInputValue<V>): ComparableRangeValue => {
+			if (value == null) {
+				return value;
+			}
+
+			if (typeof value === 'string') {
+				return baseCodec.decodeValue(value);
+			}
+
+			return value;
+		};
+
+		const assertBounds = (value: RuntimeInputValue<V>) => {
+			const comparableValue = toComparableValue(value);
+
+			if (comparableValue == null) {
+				return;
+			}
+
+			if (comparableValue < min || comparableValue > max) {
+				throw new ValueTypeInvariantError(
+					valueType,
+					`Expected value to be within bounds [${min}, ${max}]. Got: ${value}`
+				);
+			}
+		};
+
+		const encodeValue = (value: RangeInputValue<V>): string => {
+			assertBounds(value);
+
+			return baseCodec.encodeValue(value);
+		};
+
+		const decodeValue = (value: string): RangeValue<V> => {
+			const decoded = baseCodec.decodeValue(value);
+
+			assertBounds(value);
+
+			return decoded;
+		};
+
+		super(valueType, encodeValue, decodeValue);
+	}
+}

package/src/lib/codecs/TriggerCodec.ts

@@ -0,0 +1,64 @@
+import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
+import { ErrorProductionDesignPendingError } from '../../error/ErrorProductionDesignPendingError.ts';
+import { ValueCodec } from './ValueCodec.ts';
+
+export type TriggerValueType = 'string';
+
+export type TriggerRuntimeValue = boolean;
+
+export type TriggerInputValue = boolean | '' | null;
+
+type BaseTriggerInstanceValueMapping = Readonly<Record<string, string>>;
+
+const TRIGGER_INSTANCE_VALUES = {
+	true: 'OK',
+	false: '',
+} as const satisfies BaseTriggerInstanceValueMapping;
+
+type TriggerInstanceValueMapping = typeof TRIGGER_INSTANCE_VALUES;
+
+type TriggerInstanceValue = TriggerInstanceValueMapping[keyof TriggerInstanceValueMapping];
+
+const encodeTriggerValue = (value: TriggerInputValue): TriggerInstanceValue => {
+	switch (value) {
+		case true:
+			return TRIGGER_INSTANCE_VALUES.true;
+
+		case false:
+		case '':
+		case null:
+			return TRIGGER_INSTANCE_VALUES.false;
+
+		default:
+			throw new UnreachableError(value);
+	}
+};
+
+const decodeTriggerValue = (value: string): TriggerRuntimeValue => {
+	if (value === 'OK') {
+		return true;
+	}
+
+	if (value === '') {
+		return false;
+	}
+
+	if (value.toLowerCase() === 'ok') {
+		// eslint-disable-next-line no-console
+		console.warn('Treating trigger value as case-insensitive:', value);
+
+		return true;
+	}
+
+	throw new ErrorProductionDesignPendingError(`Unexpected trigger value: ${value}`);
+};
+
+export class TriggerCodec extends ValueCodec<
+	TriggerValueType,
+	TriggerRuntimeValue,
+	TriggerInputValue
+> {
+	constructor() {
+		super('string', encodeTriggerValue, decodeTriggerValue);
+	}
+}

package/src/lib/codecs/ValueArrayCodec.ts

@@ -0,0 +1,42 @@
+import type { ValueType } from '../../client/ValueType.ts';
+import { ErrorProductionDesignPendingError } from '../../error/ErrorProductionDesignPendingError.ts';
+import type { RuntimeValue, SharedValueCodec } from './getSharedValueCodec.ts';
+import type { CodecDecoder, CodecEncoder } from './ValueCodec.ts';
+import { ValueCodec } from './ValueCodec.ts';
+
+export type SplitInstanceValues = (value: string) => readonly string[];
+
+export type JoinInstnaceValues = (values: readonly string[]) => string;
+
+export type RuntimeItemValue<V extends ValueType> = NonNullable<RuntimeValue<V>>;
+
+export type RuntimeValues<V extends ValueType> = ReadonlyArray<RuntimeItemValue<V>>;
+
+export abstract class ValueArrayCodec<
+	V extends ValueType,
+	Values extends RuntimeValues<V> = RuntimeValues<V>,
+> extends ValueCodec<V, Values, Values> {
+	readonly decodeItemValue: CodecDecoder<RuntimeItemValue<V>>;
+
+	constructor(
+		baseCodec: SharedValueCodec<V>,
+		encodeValue: CodecEncoder<Values>,
+		decodeValue: CodecDecoder<Values>
+	) {
+		const decodeItemValue: CodecDecoder<RuntimeItemValue<V>> = (value) => {
+			const decoded = baseCodec.decodeValue(value);
+
+			if (decoded == null) {
+				throw new ErrorProductionDesignPendingError(
+					`Failed to decode item value: ${JSON.stringify(value)}`
+				);
+			}
+
+			return decoded;
+		};
+
+		super(baseCodec.valueType, encodeValue, decodeValue);
+
+		this.decodeItemValue = decodeItemValue;
+	}
+}

package/src/lib/codecs/ValueCodec.ts

@@ -3,9 +3,9 @@ import type { ValueType } from '../../client/ValueType.ts';
 import type { DecodeInstanceValue } from '../../instance/internal-api/InstanceValueContext.ts';
 import type { SimpleAtomicState } from '../reactivity/types.ts';
 
-type CodecEncoder<RuntimeInputValue> = (input: RuntimeInputValue) => string;
+export type CodecEncoder<RuntimeInputValue> = (input: RuntimeInputValue) => string;
 
-type CodecDecoder<RuntimeValue> = (value: string) => RuntimeValue;
+export type CodecDecoder<RuntimeValue> = (value: string) => RuntimeValue;
 
 type RuntimeValueAccessor<RuntimeValue> = Accessor<RuntimeValue>;
 

package/src/lib/codecs/getNoteCodec.ts

@@ -0,0 +1,27 @@
+import type { ValueType } from '../../client/ValueType.ts';
+import { sharedValueCodecs } from './getSharedValueCodec.ts';
+import { NoteCodec } from './NoteCodec.ts';
+
+type NoteCodecs = {
+	readonly [V in ValueType]: NoteCodec<V>;
+};
+
+const noteCodecs: NoteCodecs = {
+	string: new NoteCodec(sharedValueCodecs.string),
+	int: new NoteCodec(sharedValueCodecs.int),
+	decimal: new NoteCodec(sharedValueCodecs.decimal),
+	boolean: new NoteCodec(sharedValueCodecs.boolean),
+	date: new NoteCodec(sharedValueCodecs.date),
+	time: new NoteCodec(sharedValueCodecs.time),
+	dateTime: new NoteCodec(sharedValueCodecs.dateTime),
+	geopoint: new NoteCodec(sharedValueCodecs.geopoint),
+	geotrace: new NoteCodec(sharedValueCodecs.geotrace),
+	geoshape: new NoteCodec(sharedValueCodecs.geoshape),
+	binary: new NoteCodec(sharedValueCodecs.binary),
+	barcode: new NoteCodec(sharedValueCodecs.barcode),
+	intent: new NoteCodec(sharedValueCodecs.intent),
+};
+
+export const getNoteCodec = <V extends ValueType>(valueType: V): NoteCodec<V> => {
+	return noteCodecs[valueType];
+};

package/src/lib/codecs/getSelectCodec.ts

@@ -0,0 +1,27 @@
+import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
+import type { SelectDefinition } from '../../client/SelectNode.ts';
+import { sharedValueCodecs } from './getSharedValueCodec.ts';
+import { MultipleValueItemCodec } from './items/MultipleValueItemCodec.ts';
+import { SingleValueItemCodec } from './items/SingleValueItemCodec.ts';
+
+const multipleValueSelectCodec = new MultipleValueItemCodec(sharedValueCodecs.string);
+
+const singleValueSelectCodec = new SingleValueItemCodec(sharedValueCodecs.string);
+
+// prettier-ignore
+export type SelectCodec =
+	| MultipleValueItemCodec
+	| SingleValueItemCodec;
+
+export const getSelectCodec = (definition: SelectDefinition<'string'>): SelectCodec => {
+	switch (definition.bodyElement.type) {
+		case 'select':
+			return multipleValueSelectCodec;
+
+		case 'select1':
+			return singleValueSelectCodec;
+
+		default:
+			throw new UnreachableError(definition.bodyElement.type);
+	}
+};

package/src/lib/codecs/getSharedValueCodec.ts

@@ -4,6 +4,8 @@ import {
 	type DecimalInputValue,
 	type DecimalRuntimeValue,
 } from './DecimalValueCodec.ts';
+import type { GeopointInputValue, GeopointRuntimeValue } from './Geopoint/Geopoint.ts';
+import { GeopointValueCodec } from './Geopoint/GeopointValueCodec.ts';
 import { IntValueCodec, type IntInputValue, type IntRuntimeValue } from './IntValueCodec.ts';
 import { StringValueCodec } from './StringValueCodec.ts';
 import type { ValueCodec } from './ValueCodec.ts';
@@ -17,7 +19,7 @@ interface RuntimeValuesByType {
 	readonly date: string;
 	readonly time: string;
 	readonly dateTime: string;
-	readonly geopoint: string;
+	readonly geopoint: GeopointRuntimeValue;
 	readonly geotrace: string;
 	readonly geoshape: string;
 	readonly binary: string;
@@ -35,7 +37,7 @@ interface RuntimeInputValuesByType {
 	readonly date: string;
 	readonly time: string;
 	readonly dateTime: string;
-	readonly geopoint: string;
+	readonly geopoint: GeopointInputValue;
 	readonly geotrace: string;
 	readonly geoshape: string;
 	readonly binary: string;
@@ -64,7 +66,7 @@ export const sharedValueCodecs: SharedValueCodecs = {
 	date: new ValueTypePlaceholderCodec('date'),
 	time: new ValueTypePlaceholderCodec('time'),
 	dateTime: new ValueTypePlaceholderCodec('dateTime'),
-	geopoint: new ValueTypePlaceholderCodec('geopoint'),
+	geopoint: new GeopointValueCodec(),
 	geotrace: new ValueTypePlaceholderCodec('geotrace'),
 	geoshape: new ValueTypePlaceholderCodec('geoshape'),
 	binary: new ValueTypePlaceholderCodec('binary'),

package/src/lib/codecs/items/BaseItemCodec.ts

@@ -0,0 +1,20 @@
+import type { ValueType } from '../../../client/ValueType.ts';
+import type { SharedValueCodec } from '../getSharedValueCodec.ts';
+import { ValueArrayCodec } from '../ValueArrayCodec.ts';
+import type { CodecDecoder, CodecEncoder } from '../ValueCodec.ts';
+
+export type BaseItemValueType = 'string';
+
+export type UnsupportedBaseItemValueType = Exclude<ValueType, BaseItemValueType>;
+
+export abstract class BaseItemCodec<
+	Values extends readonly string[] = readonly string[],
+> extends ValueArrayCodec<BaseItemValueType, Values> {
+	constructor(
+		baseCodec: SharedValueCodec<'string'>,
+		encodeValue: CodecEncoder<Values>,
+		decodeValue: CodecDecoder<Values>
+	) {
+		super(baseCodec, encodeValue, decodeValue);
+	}
+}

package/src/lib/codecs/items/MultipleValueItemCodec.ts

@@ -0,0 +1,28 @@
+import { xmlXPathWhitespaceSeparatedList } from '@getodk/common/lib/string/whitespace.ts';
+import type { SharedValueCodec } from '../getSharedValueCodec.ts';
+import type { CodecDecoder, CodecEncoder } from '../ValueCodec.ts';
+import { BaseItemCodec } from './BaseItemCodec.ts';
+
+/**
+ * Value codec implementation for `<select>` and `<odk:rank>` controls.
+ *
+ * This generalizes the application of a {@link SharedValueCodec} implementation
+ * over individual select and rank values, where those values are serialized as a
+ * whitespace-separated list. All other encoding and decoding logic is deferred
+ * to the provided {@link baseCodec}, ensuring that select and rank value types are
+ * treated consistently with the same underlying data types for other controls.
+ */
+export class MultipleValueItemCodec extends BaseItemCodec<readonly string[]> {
+	constructor(baseCodec: SharedValueCodec<'string'>) {
+		const encodeValue: CodecEncoder<readonly string[]> = (value) => {
+			return value.join(' ');
+		};
+		const decodeValue: CodecDecoder<readonly string[]> = (value) => {
+			return xmlXPathWhitespaceSeparatedList(value, {
+				ignoreEmpty: true,
+			});
+		};
+
+		super(baseCodec, encodeValue, decodeValue);
+	}
+}

package/src/lib/codecs/items/SingleValueItemCodec.ts

@@ -0,0 +1,67 @@
+import type { SharedValueCodec } from '../getSharedValueCodec.ts';
+import { type CodecDecoder, type CodecEncoder } from '../ValueCodec.ts';
+import { BaseItemCodec } from './BaseItemCodec.ts';
+import type { MultipleValueItemCodec } from './MultipleValueItemCodec.ts';
+
+// prettier-ignore
+export type SingleValueSelectRuntimeValues =
+	| readonly []
+	| readonly [string];
+
+/**
+ * @see {@link encodeValueFactory}
+ */
+// prettier-ignore
+type SingleValueSelectCodecValues =
+	| SingleValueSelectRuntimeValues
+	| readonly string[];
+
+/**
+ * @todo This is more permissive than it should be, allowing an array of any
+ * length.  It's not clear whether a runtime check **MUST** happen here, but
+ * if we identify bugs where `<select1>` controls are somehow allowing more
+ * than one value to be set, this is where we'd start looking. The check is
+ * skipped for now, to reduce performance overhead.
+ */
+const encodeValueFactory = (
+	baseCodec: SharedValueCodec<'string'>
+): CodecEncoder<SingleValueSelectCodecValues> => {
+	return (values) => {
+		const [value] = values;
+
+		if (value == null) {
+			return '';
+		}
+
+		return baseCodec.encodeValue(value);
+	};
+};
+
+/**
+ * Value codec implementation for `<select1>` controls.
+ *
+ * Note: this implementation is a specialization of the same principles
+ * underlying {@link MultipleValueItemCodec}. It is implemented separately:
+ *
+ * 1. to address a semantic difference between `<select>` and `<select1>`
+ *    values: the former are serialized as a space-separated list, but that does
+ *    not apply to the latter;
+ *
+ * 2. as an optimization, as the more general implementation performs poorly on
+ *    forms which we monitor for performance.
+ */
+export class SingleValueItemCodec extends BaseItemCodec<SingleValueSelectCodecValues> {
+	constructor(baseCodec: SharedValueCodec<'string'>) {
+		const encodeValue = encodeValueFactory(baseCodec);
+
+		const decodeValue: CodecDecoder<SingleValueSelectRuntimeValues> = (value) => {
+			if (value == null) {
+				return [];
+			}
+
+			return [value];
+		};
+
+		super(baseCodec, encodeValue, decodeValue);
+	}
+}

package/src/lib/dom/query.ts

@@ -3,7 +3,6 @@ import type {
 	KnownAttributeLocalNamedElement,
 	LocalNamedElement,
 } from '@getodk/common/types/dom.ts';
-import type { SelectElement } from '../../parse/body/control/select/SelectDefinition';
 
 const hintLookup = new ScopedElementLookup(':scope > hint', 'hint');
 const itemLookup = new ScopedElementLookup(':scope > item', 'item');
@@ -38,7 +37,7 @@ export const getHintElement = (parent: Element): HintElement | null => {
 	return hintLookup.getElement<HintElement>(parent);
 };
 
-export const getItemElements = (parent: SelectElement): readonly ItemElement[] => {
+export const getItemElements = (parent: Element): readonly ItemElement[] => {
 	return Array.from(itemLookup.getElements<ItemElement>(parent));
 };