@getodk/xforms-engine 0.4.0 → 0.6.0

package/src/instance/SelectField.ts

@@ -1,226 +0,0 @@
-import { xmlXPathWhitespaceSeparatedList } from '@getodk/common/lib/string/whitespace.ts';
-import type { Accessor } from 'solid-js';
-import { untrack } from 'solid-js';
-import type { SelectItem, SelectNode, SelectNodeAppearances } from '../client/SelectNode.ts';
-import type { TextRange } from '../client/TextRange.ts';
-import type { AnyViolation, LeafNodeValidationState } from '../client/validation.ts';
-import { createSelectItems } from '../lib/reactivity/createSelectItems.ts';
-import { createValueState } from '../lib/reactivity/createValueState.ts';
-import type { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
-import type { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
-import type { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
-import { createSharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
-import { createFieldHint } from '../lib/reactivity/text/createFieldHint.ts';
-import { createNodeLabel } from '../lib/reactivity/text/createNodeLabel.ts';
-import type { SimpleAtomicState } from '../lib/reactivity/types.ts';
-import type { SharedValidationState } from '../lib/reactivity/validation/createValidation.ts';
-import { createValidationState } from '../lib/reactivity/validation/createValidation.ts';
-import type { AnySelectDefinition } from '../parse/body/control/select/SelectDefinition.ts';
-import type { LeafNodeDefinition } from '../parse/model/LeafNodeDefinition.ts';
-import type { Root } from './Root.ts';
-import type { DescendantNodeStateSpec } from './abstract/DescendantNode.ts';
-import { DescendantNode } from './abstract/DescendantNode.ts';
-import type { GeneralParentNode } from './hierarchy.ts';
-import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
-import type { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
-import type { ValidationContext } from './internal-api/ValidationContext.ts';
-import type { ValueContext } from './internal-api/ValueContext.ts';
-
-export interface SelectFieldDefinition extends LeafNodeDefinition {
-	readonly bodyElement: AnySelectDefinition;
-}
-
-interface SelectFieldStateSpec extends DescendantNodeStateSpec<readonly SelectItem[]> {
-	readonly label: Accessor<TextRange<'label'> | null>;
-	readonly hint: Accessor<TextRange<'hint'> | null>;
-	readonly children: null;
-	readonly value: SimpleAtomicState<readonly SelectItem[]>;
-	readonly valueOptions: Accessor<readonly SelectItem[]>;
-}
-
-export class SelectField
-	extends DescendantNode<SelectFieldDefinition, SelectFieldStateSpec, null>
-	implements
-		SelectNode,
-		EvaluationContext,
-		SubscribableDependency,
-		ValidationContext,
-		ValueContext<readonly SelectItem[]>
-{
-	private readonly selectExclusive: boolean;
-	private readonly validation: SharedValidationState;
-
-	// InstanceNode
-	protected readonly state: SharedNodeState<SelectFieldStateSpec>;
-	protected override engineState: EngineState<SelectFieldStateSpec>;
-
-	// SelectNode
-	readonly nodeType = 'select';
-	readonly appearances: SelectNodeAppearances;
-	readonly currentState: CurrentState<SelectFieldStateSpec>;
-
-	get validationState(): LeafNodeValidationState {
-		return this.validation.currentState;
-	}
-
-	// ValueContext
-	readonly encodeValue = (runtimeValue: readonly SelectItem[]): string => {
-		const itemValues = new Set(runtimeValue.map(({ value }) => value));
-
-		return Array.from(itemValues).join(' ');
-	};
-
-	readonly decodeValue = (instanceValue: string): readonly SelectItem[] => {
-		return this.scope.runTask(() => {
-			const values = xmlXPathWhitespaceSeparatedList(instanceValue, {
-				ignoreEmpty: true,
-			});
-
-			const items = this.getSelectItemsByValue();
-
-			return values
-				.map((value) => {
-					return items.get(value);
-				})
-				.filter((item): item is SelectItem => {
-					return item != null;
-				});
-		});
-	};
-
-	protected readonly getValueOptions: Accessor<readonly SelectItem[]>;
-
-	constructor(parent: GeneralParentNode, definition: SelectFieldDefinition) {
-		super(parent, definition);
-
-		this.appearances = definition.bodyElement.appearances;
-		this.selectExclusive = definition.bodyElement.type === 'select1';
-
-		const valueOptions = createSelectItems(this);
-
-		this.getValueOptions = valueOptions;
-
-		const sharedStateOptions = {
-			clientStateFactory: this.engineConfig.stateFactory,
-		};
-
-		const state = createSharedNodeState(
-			this.scope,
-			{
-				reference: this.contextReference,
-				readonly: this.isReadonly,
-				relevant: this.isRelevant,
-				required: this.isRequired,
-
-				label: createNodeLabel(this, definition),
-				hint: createFieldHint(this, definition),
-				children: null,
-				value: createValueState(this),
-				valueOptions,
-			},
-			sharedStateOptions
-		);
-
-		this.state = state;
-		this.engineState = state.engineState;
-		this.currentState = state.currentState;
-		this.validation = createValidationState(this, sharedStateOptions);
-	}
-
-	protected getSelectItemsByValue(
-		valueOptions: readonly SelectItem[] = this.getValueOptions()
-	): ReadonlyMap<string, SelectItem> {
-		return new Map(
-			valueOptions.map((item) => {
-				return [item.value, item];
-			})
-		);
-	}
-
-	protected updateSelectedItemValues(values: readonly string[]) {
-		const itemsByValue = untrack(() => this.getSelectItemsByValue());
-
-		const items = values.flatMap((value) => {
-			const item = itemsByValue.get(value);
-
-			if (item == null) {
-				return [];
-			}
-
-			return item ?? [];
-		});
-
-		this.state.setProperty('value', items);
-	}
-
-	protected setSelectedItemValue(value: string | null) {
-		if (value == null) {
-			this.state.setProperty('value', []);
-
-			return;
-		}
-
-		this.updateSelectedItemValues([value]);
-	}
-
-	// SelectNode
-	select(selectedItem: SelectItem): Root {
-		const { engineState, root } = this;
-
-		if (this.selectExclusive) {
-			this.setSelectedItemValue(selectedItem.value);
-
-			return root;
-		}
-
-		const currentValues = engineState.value.map(({ value }) => {
-			return value;
-		});
-
-		const selectedValue = selectedItem.value;
-
-		if (currentValues.includes(selectedValue)) {
-			return root;
-		}
-
-		this.updateSelectedItemValues(currentValues.concat(selectedValue));
-
-		return root;
-	}
-
-	deselect(deselectedItem: SelectItem): Root {
-		const { engineState, root } = this;
-
-		const currentValues = engineState.value.map(({ value }) => {
-			return value;
-		});
-
-		const selectedValue = deselectedItem.value;
-
-		if (!currentValues.includes(selectedValue)) {
-			return root;
-		}
-
-		const updatedValues = currentValues.filter((value) => {
-			return value !== selectedValue;
-		});
-
-		this.updateSelectedItemValues(updatedValues);
-
-		return root;
-	}
-
-	// InstanceNode
-	getChildren(): readonly [] {
-		return [];
-	}
-
-	// ValidationContext
-	getViolation(): AnyViolation | null {
-		return this.validation.engineState.violation;
-	}
-
-	isBlank(): boolean {
-		return this.engineState.value.length === 0;
-	}
-}

package/src/instance/StringField.ts

@@ -1,120 +0,0 @@
-import { identity } from '@getodk/common/lib/identity.ts';
-import type { Accessor } from 'solid-js';
-import type { StringNode, StringNodeAppearances } from '../client/StringNode.ts';
-import type { TextRange } from '../client/TextRange.ts';
-import type { AnyViolation, LeafNodeValidationState } from '../client/validation.ts';
-import { createValueState } from '../lib/reactivity/createValueState.ts';
-import type { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
-import type { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
-import type { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
-import { createSharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
-import { createFieldHint } from '../lib/reactivity/text/createFieldHint.ts';
-import { createNodeLabel } from '../lib/reactivity/text/createNodeLabel.ts';
-import type { SimpleAtomicState } from '../lib/reactivity/types.ts';
-import type { SharedValidationState } from '../lib/reactivity/validation/createValidation.ts';
-import { createValidationState } from '../lib/reactivity/validation/createValidation.ts';
-import type { InputDefinition } from '../parse/body/control/InputDefinition.ts';
-import type { LeafNodeDefinition } from '../parse/model/LeafNodeDefinition.ts';
-import type { Root } from './Root.ts';
-import type { DescendantNodeStateSpec } from './abstract/DescendantNode.ts';
-import { DescendantNode } from './abstract/DescendantNode.ts';
-import type { GeneralParentNode } from './hierarchy.ts';
-import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
-import type { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
-import type { ValidationContext } from './internal-api/ValidationContext.ts';
-import type { ValueContext } from './internal-api/ValueContext.ts';
-
-export interface StringFieldDefinition extends LeafNodeDefinition {
-	readonly bodyElement: InputDefinition;
-}
-
-interface StringFieldStateSpec extends DescendantNodeStateSpec<string> {
-	readonly label: Accessor<TextRange<'label'> | null>;
-	readonly hint: Accessor<TextRange<'hint'> | null>;
-	readonly children: null;
-	readonly value: SimpleAtomicState<string>;
-	readonly valueOptions: null;
-}
-
-export class StringField
-	extends DescendantNode<StringFieldDefinition, StringFieldStateSpec, null>
-	implements
-		StringNode,
-		EvaluationContext,
-		SubscribableDependency,
-		ValidationContext,
-		ValueContext<string>
-{
-	private readonly validation: SharedValidationState;
-	protected readonly state: SharedNodeState<StringFieldStateSpec>;
-
-	// InstanceNode
-	protected engineState: EngineState<StringFieldStateSpec>;
-
-	// StringNode
-	readonly nodeType = 'string';
-	readonly appearances: StringNodeAppearances;
-	readonly currentState: CurrentState<StringFieldStateSpec>;
-
-	get validationState(): LeafNodeValidationState {
-		return this.validation.currentState;
-	}
-
-	// ValueContext
-	readonly encodeValue = identity<string>;
-
-	readonly decodeValue = identity<string>;
-
-	constructor(parent: GeneralParentNode, definition: StringFieldDefinition) {
-		super(parent, definition);
-
-		this.appearances = definition.bodyElement.appearances;
-
-		const sharedStateOptions = {
-			clientStateFactory: this.engineConfig.stateFactory,
-		};
-
-		const state = createSharedNodeState(
-			this.scope,
-			{
-				reference: this.contextReference,
-				readonly: this.isReadonly,
-				relevant: this.isRelevant,
-				required: this.isRequired,
-
-				label: createNodeLabel(this, definition),
-				hint: createFieldHint(this, definition),
-				children: null,
-				valueOptions: null,
-				value: createValueState(this),
-			},
-			sharedStateOptions
-		);
-
-		this.state = state;
-		this.engineState = state.engineState;
-		this.currentState = state.currentState;
-		this.validation = createValidationState(this, sharedStateOptions);
-	}
-
-	// ValidationContext
-	getViolation(): AnyViolation | null {
-		return this.validation.engineState.violation;
-	}
-
-	isBlank(): boolean {
-		return this.engineState.value === '';
-	}
-
-	// InstanceNode
-	getChildren(): readonly [] {
-		return [];
-	}
-
-	// StringNode
-	setValue(value: string): Root {
-		this.state.setProperty('value', value);
-
-		return this.root;
-	}
-}

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

@@ -1,61 +0,0 @@
-import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
-import type { EvaluationContext } from './EvaluationContext.ts';
-
-/**
- * Provides a common interface to explicitly establish a reactive subscription
- * to a form node, regardless of which node-specific details might trigger
- * reactive updates. This is primarily intended for use in coordination with a
- * node's {@link EvaluationContext} interface, so that computed expression
- * evaluations can be re-executed when their dependencies update, without
- * requiring a given evaluation to handle node-specific logic to determine
- * when/whether updates have occurred.
- *
- * @example Given a form with these bindings:
- *
- * ```xml
- * <bind nodeset="/data/field-1" />
- * <bind nodeset="/data/field-2" type="int" />
- * <bind nodeset="/data/group-a" relevant="/data/field-1 != ''" />
- * <bind nodeset="/data/group-a/field-a-1" calculate="/data/field-2 * 2" />
- * ```
- *
- * The field `/data/group-a/field-a-1`'s calculate has two dependencies:
- *
- * - `/data-field-2` (explicit)
- * - `/data/group-a` (implicit: non-relevance is inherited)
- *
- * (This is an oversimplification, but it helps to illustrate the concept.)
- *
- * The first dependency's subscription is clearly concerned with that leaf
- * node's value. In which case, that node's `subscribe` method should react to
- * updates to its value (e.g. its `currentState.value` or the internal reactive
- * representation thereof).
- *
- * Whereas the second dependency has no value (no parent nodes do); instead, the
- * subscription would be concerned with that node's relevance. In which case,
- * that node's `subscribe` method should react to updates to its relevance state
- * (e.g. its `currentState.relevant` or the internal reactive represeentation
- * thereof).
- *
- * @example Given a form with:
- *
- * ```xml
- * <!-- model -->
- * <bind nodeset="/data/repeat-a/field-a-1" calculate="position(..)" />
- * <!-- body -->
- * <repeat nodeset="/data/repeat-a" />
- * ```
- *
- * The field `/data/repeat-a/field-a-1` has a dependency on its containing
- * repeat instance. That node also doesn't have a value, and here the dynamic
- * aspect of the dependency is the node's current position. Here the node's
- * `subscribe` method should react to changes in its position (likely indirectly
- * by reading its `contextReference`).
- *
- * @see {@link EvaluationContext}
- * @see {@link EvaluationContext.contextReference}
- */
-export interface SubscribableDependency {
-	readonly scope: ReactiveScope;
-	readonly subscribe: VoidFunction;
-}

package/src/instance/unsupported/RangeControl.ts

@@ -1,5 +0,0 @@
-import { UnsupportedControl } from '../abstract/UnsupportedControl.ts';
-
-export class RangeControl extends UnsupportedControl<'range'> {
-	readonly nodeType = 'range';
-}

package/src/instance/unsupported/RankControl.ts

@@ -1,5 +0,0 @@
-import { UnsupportedControl } from '../abstract/UnsupportedControl.ts';
-
-export class RankControl extends UnsupportedControl<'rank'> {
-	readonly nodeType = 'rank';
-}

package/src/lib/reactivity/createSelectItems.ts

@@ -1,168 +0,0 @@
-import { UpsertableMap } from '@getodk/common/lib/collections/UpsertableMap.ts';
-import type { XFormsXPathEvaluator } from '@getodk/xpath';
-import type { Accessor } from 'solid-js';
-import { createMemo } from 'solid-js';
-import type { TextRange as ClientTextRange } from '../../client/TextRange.ts';
-import type { SelectItem } from '../../index.ts';
-import type { SelectField } from '../../instance/SelectField.ts';
-import type {
-	EvaluationContext,
-	EvaluationContextRoot,
-} from '../../instance/internal-api/EvaluationContext.ts';
-import type { SubscribableDependency } from '../../instance/internal-api/SubscribableDependency.ts';
-import { TextChunk } from '../../instance/text/TextChunk.ts';
-import { TextRange } from '../../instance/text/TextRange.ts';
-import type { ItemDefinition } from '../../parse/body/control/select/ItemDefinition.ts';
-import type { ItemsetDefinition } from '../../parse/body/control/select/ItemsetDefinition.ts';
-import { createComputedExpression } from './createComputedExpression.ts';
-import type { ReactiveScope } from './scope.ts';
-import { createTextRange } from './text/createTextRange.ts';
-
-type DerivedItemLabel = ClientTextRange<'item-label', 'form-derived'>;
-
-const derivedItemLabel = (context: EvaluationContext, value: string): DerivedItemLabel => {
-	const chunk = new TextChunk(context.root, 'literal', value);
-
-	return new TextRange('form-derived', 'item-label', [chunk]);
-};
-
-const createSelectItemLabel = (
-	context: EvaluationContext,
-	definition: ItemDefinition
-): Accessor<ClientTextRange<'item-label'>> => {
-	const { label, value } = definition;
-
-	if (label == null) {
-		return () => derivedItemLabel(context, value);
-	}
-
-	return createTextRange(context, 'item-label', label);
-};
-
-const createTranslatedStaticSelectItems = (
-	selectField: SelectField,
-	items: readonly ItemDefinition[]
-): Accessor<readonly SelectItem[]> => {
-	return selectField.scope.runTask(() => {
-		const labeledItems = items.map((item) => {
-			const { value } = item;
-			const label = createSelectItemLabel(selectField, item);
-
-			return () => ({
-				value,
-				label: label(),
-			});
-		});
-
-		return createMemo(() => {
-			return labeledItems.map((item) => item());
-		});
-	});
-};
-
-class ItemsetItemEvaluationContext implements EvaluationContext {
-	readonly scope: ReactiveScope;
-	readonly evaluator: XFormsXPathEvaluator;
-	readonly root: EvaluationContextRoot;
-	readonly contextReference: Accessor<string>;
-
-	constructor(
-		private readonly selectField: SelectField,
-		readonly contextNode: Node
-	) {
-		this.scope = selectField.scope;
-		this.evaluator = selectField.evaluator;
-		this.root = selectField.root;
-		this.contextReference = selectField.contextReference;
-	}
-
-	getSubscribableDependenciesByReference(reference: string): readonly SubscribableDependency[] {
-		return this.selectField.getSubscribableDependenciesByReference(reference);
-	}
-}
-
-const createSelectItemsetItemLabel = (
-	context: EvaluationContext,
-	definition: ItemsetDefinition,
-	itemValue: Accessor<string>
-): Accessor<ClientTextRange<'item-label'>> => {
-	const { label } = definition;
-
-	if (label == null) {
-		return createMemo(() => {
-			return derivedItemLabel(context, itemValue());
-		});
-	}
-
-	return createTextRange(context, 'item-label', label);
-};
-
-interface ItemsetItem {
-	label(): ClientTextRange<'item-label'>;
-	value(): string;
-}
-
-const createItemsetItems = (
-	selectField: SelectField,
-	itemset: ItemsetDefinition
-): Accessor<readonly ItemsetItem[]> => {
-	return selectField.scope.runTask(() => {
-		const itemNodes = createComputedExpression(selectField, itemset.nodes);
-		const itemsCache = new UpsertableMap<Node, ItemsetItem>();
-
-		return createMemo(() => {
-			return itemNodes().map((itemNode) => {
-				return itemsCache.upsert(itemNode, () => {
-					const context = new ItemsetItemEvaluationContext(selectField, itemNode);
-					const value = createComputedExpression(context, itemset.value);
-					const label = createSelectItemsetItemLabel(context, itemset, value);
-
-					return {
-						label,
-						value,
-					};
-				});
-			});
-		});
-	});
-};
-
-const createItemset = (
-	selectField: SelectField,
-	itemset: ItemsetDefinition
-): Accessor<readonly SelectItem[]> => {
-	return selectField.scope.runTask(() => {
-		const itemsetItems = createItemsetItems(selectField, itemset);
-
-		return createMemo(() => {
-			return itemsetItems().map((item) => {
-				return {
-					label: item.label(),
-					value: item.value(),
-				};
-			});
-		});
-	});
-};
-
-/**
- * Creates a reactive computation of a {@link SelectField}'s
- * {@link SelectItem}s, in support of the field's `valueOptions`.
- *
- * - Selects 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
- *   of items.
- * - Items of both will produce {@link SelectItem.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;
-
-	if (itemset == null) {
-		return createTranslatedStaticSelectItems(selectField, items);
-	}
-
-	return createItemset(selectField, itemset);
-};

package/src/parse/XFormDataType.ts

@@ -1,62 +0,0 @@
-import type { CollectionValues } from '@getodk/common/types/collections/CollectionValues.ts';
-
-/**
- * Like JavaRosa. Presumably for explicit types which aren't impelemnted?
- */
-const UNSUPPORTED_DATA_TYPE = 'UNSUPPORTED';
-
-export type UnsupportedDataType = typeof UNSUPPORTED_DATA_TYPE;
-
-/**
- * Like JavaRosa. Presumably for e.g. groups with explicit binds (`relevant` etc)?
- */
-export type NullDataType = 'NULL';
-
-/**
- * As in ODK XForms Spec.
- *
- * TODO: it's unclear why JavaRosa's `DataType` hews closely to the spec, but
- * has certain differences (e.g. string -> TEXT, int -> INTEGER). It's also
- * not immediately clear how additive types like CHOICE and MULTIPLE_ITEMS
- * square with the underlying spec types.
- */
-export const XFORM_SPEC_DATA_TYPES = [
-	'string',
-	'int',
-	'boolean',
-	'decimal',
-	'date',
-	'time',
-	'dateTime',
-	'geopoint',
-	'geotrace',
-	'geoshape',
-	'binary',
-	'barcode',
-	'intent',
-] as const;
-
-const isSupportedDataType = (bindType: string): bindType is XFormSpecDataType =>
-	XFORM_SPEC_DATA_TYPES.includes(bindType as XFormSpecDataType);
-
-export type XFormSpecDataType = CollectionValues<typeof XFORM_SPEC_DATA_TYPES>;
-
-export type XFormDataType = NullDataType | UnsupportedDataType | XFormSpecDataType;
-
-const DEFAULT_XFORM_DATA_TYPE = 'string';
-
-export type DefaultXFormDataType = typeof DEFAULT_XFORM_DATA_TYPE;
-
-// TODO: groups -> NULL?
-// TODO: XSD namespace
-export const bindDataType = (bindType: string | null): XFormDataType => {
-	if (bindType == null) {
-		return DEFAULT_XFORM_DATA_TYPE;
-	}
-
-	if (isSupportedDataType(bindType)) {
-		return bindType;
-	}
-
-	return UNSUPPORTED_DATA_TYPE;
-};

package/src/parse/body/control/InputDefinition.ts

@@ -1,22 +0,0 @@
-import type { XFormDefinition } from '../../XFormDefinition.ts';
-import {
-	inputAppearanceParser,
-	type InputAppearanceDefinition,
-} from '../appearance/inputAppearanceParser.ts';
-import type { BodyElementParentContext } from '../BodyDefinition.ts';
-import { ControlDefinition } from './ControlDefinition.ts';
-
-export class InputDefinition extends ControlDefinition<'input'> {
-	static override isCompatible(localName: string): boolean {
-		return localName === 'input';
-	}
-
-	readonly type = 'input';
-	readonly appearances: InputAppearanceDefinition;
-
-	constructor(form: XFormDefinition, parent: BodyElementParentContext, element: Element) {
-		super(form, parent, element);
-
-		this.appearances = inputAppearanceParser.parseFrom(element, 'appearance');
-	}
-}