@getodk/xforms-engine 0.6.0 → 0.8.0

package/src/lib/reactivity/createValueState.ts

@@ -1,200 +0,0 @@
-import { createComputed, createMemo, createSignal, untrack, type Signal } from 'solid-js';
-import { ErrorProductionDesignPendingError } from '../../error/ErrorProductionDesignPendingError.ts';
-import type { ValueContext } from '../../instance/internal-api/ValueContext.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 ValueStateOptions {
-	/**
-	 * Specifies the source of a {@link createValueState} 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 createV} 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 = <RuntimeValue>(
-	context: ValueContext<RuntimeValue>,
-	options: ValueStateOptions
-): string => {
-	const { initialValueSource = 'FORM_DEFAULT' } = options;
-
-	if (initialValueSource === 'FORM_DEFAULT') {
-		return context.definition.defaultValue;
-	}
-
-	throw new ErrorProductionDesignPendingError('Edit implementation pending');
-};
-
-type BaseValueState = Signal<string>;
-
-type RelevantValueState = SimpleAtomicState<string>;
-
-/**
- * Wraps {@link baseValueState} in a signal-like interface which:
- *
- * - produces a blank value for nodes ({@link context}) in a non-relevant state
- * - persists, and restores, the most recent non-blank value state when a
- *   node/context's relevance is restored
- */
-const createRelevantValueState = <RuntimeValue>(
-	context: ValueContext<RuntimeValue>,
-	baseValueState: BaseValueState
-): RelevantValueState => {
-	return context.scope.runTask(() => {
-		const [getRelevantValue, setValue] = baseValueState;
-
-		const getValue = createMemo(() => {
-			if (context.isRelevant()) {
-				return getRelevantValue();
-			}
-
-			return '';
-		});
-
-		return [getValue, setValue];
-	});
-};
-
-type RuntimeValueState<RuntimeValue> = SimpleAtomicState<RuntimeValue>;
-
-/**
- * Wraps {@link relevantValueState} in a signal-like interface which
- * automatically encodes and decodes a node's runtime value representation:
- *
- * - Values read by a node will be read from the current state as persisted in
- *   the primary instance, then {@link ValueContext.decodeValue | decoded} (as
- *   implemented by that node) into a format suitable for the rest of the
- *   functionality provided by that node.
- *
- * - Values written by a node will be {@link ValueContext.encodeValue | encoded}
- *   (also as implemented by that node) into a string value appropriate for
- *   serialization in an instance submission.
- */
-const createRuntimeValueState = <RuntimeValue>(
-	context: ValueContext<RuntimeValue>,
-	relevantValueState: RelevantValueState
-): RuntimeValueState<RuntimeValue> => {
-	const { decodeValue, encodeValue } = context;
-
-	return context.scope.runTask(() => {
-		const [primaryInstanceValue, setPrimaryInstanceValue] = relevantValueState;
-		const getRuntimeValue = createMemo(() => {
-			return decodeValue(primaryInstanceValue());
-		});
-		const setRuntimeValue: SimpleAtomicStateSetter<RuntimeValue> = (value) => {
-			const encodedValue = encodeValue(value);
-
-			return decodeValue(setPrimaryInstanceValue(encodedValue));
-		};
-
-		return [getRuntimeValue, setRuntimeValue];
-	});
-};
-
-/**
- * For fields with a `readonly` bind expression, prevent downstream
- * (client/user) writes when the field is in a `readonly` state.
- */
-const guardDownstreamReadonlyWrites = <RuntimeValue>(
-	context: ValueContext<RuntimeValue>,
-	baseState: SimpleAtomicState<RuntimeValue>
-): SimpleAtomicState<RuntimeValue> => {
-	const { readonly } = context.definition.bind;
-
-	if (readonly.isDefaultExpression) {
-		return baseState;
-	}
-
-	const [getValue, baseSetValue] = baseState;
-
-	const setValue: SimpleAtomicStateSetter<RuntimeValue> = (value) => {
-		if (context.isReadonly()) {
-			const reference = untrack(() => context.contextReference());
-
-			throw new Error(`Cannot write to readonly field: ${reference}`);
-		}
-
-		return baseSetValue(value);
-	};
-
-	return [getValue, setValue];
-};
-
-/**
- * Defines a reactive effect which writes the result of `calculate` bind
- * computations to the provided value setter, on initialization and any
- * subsequent reactive update.
- */
-const createCalculation = <RuntimeValue>(
-	context: ValueContext<RuntimeValue>,
-	setValue: SimpleAtomicStateSetter<RuntimeValue>,
-	calculateDefinition: BindComputationExpression<'calculate'>
-): void => {
-	context.scope.runTask(() => {
-		const calculate = createComputedExpression(context, calculateDefinition, {
-			defaultValue: '',
-		});
-
-		createComputed(() => {
-			if (context.isAttached() && context.isRelevant()) {
-				const calculated = calculate();
-				const value = context.decodeValue(calculated);
-
-				setValue(value);
-			}
-		});
-	});
-};
-
-type ValueState<RuntimeValue> = SimpleAtomicState<RuntimeValue>;
-
-/**
- * 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)
- * - 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 createValueState = <RuntimeValue>(
-	context: ValueContext<RuntimeValue>,
-	options: ValueStateOptions = {}
-): ValueState<RuntimeValue> => {
-	return context.scope.runTask(() => {
-		const initialValue = getInitialValue(context, options);
-		const baseValueState = createSignal(initialValue);
-		const valueState = createRelevantValueState(context, baseValueState);
-		const runtimeState = createRuntimeValueState(context, valueState);
-		const { calculate } = context.definition.bind;
-
-		if (calculate != null) {
-			const [, setValue] = runtimeState;
-
-			createCalculation(context, setValue, calculate);
-		}
-
-		return guardDownstreamReadonlyWrites(context, runtimeState);
-	});
-};

package/src/parse/model/ItextTranslation/ItextTranslationDefinition.ts

@@ -1,4 +0,0 @@
-import { StaticDocument } from '../../../integration/xpath/static-dom/StaticDocument.ts';
-import { ItextTranslationRootDefinition } from './ItextTranslationRootDefinition.ts';
-
-export class ItextTranslationDefinition extends StaticDocument<ItextTranslationRootDefinition> {}

package/src/parse/model/ItextTranslation/ItextTranslationRootDefinition.ts

@@ -1,42 +0,0 @@
-import type { XFormsItextTranslationElement } from '@getodk/xpath';
-import { XFORMS_KNOWN_ATTRIBUTE, XFORMS_LOCAL_NAME } from '@getodk/xpath';
-import { StaticElement } from '../../../integration/xpath/static-dom/StaticElement.ts';
-import type { ItextTranslationDefinition } from './ItextTranslationDefinition.ts';
-
-// prettier-ignore
-type ItextTranslationRootKnownAttributeValue<LocalName extends string> =
-	LocalName extends 'lang'
-		? string
-		: string | null;
-
-type AssertItextTranslationRootKnownAttributeValue = <LocalName extends string>(
-	localName: LocalName,
-	value: string | null
-) => asserts value is ItextTranslationRootKnownAttributeValue<LocalName>;
-
-const assertItextTranslationRootKnownAttributeValue: AssertItextTranslationRootKnownAttributeValue =
-	(localName, value) => {
-		if (localName === 'lang' && value == null) {
-			throw new Error('Invalid itext <translation> element: missing `lang` attribute');
-		}
-	};
-
-export class ItextTranslationRootDefinition
-	extends StaticElement<ItextTranslationDefinition>
-	implements XFormsItextTranslationElement<ItextTranslationRootDefinition>
-{
-	override readonly [XFORMS_LOCAL_NAME] = 'translation';
-	override readonly [XFORMS_KNOWN_ATTRIBUTE] = 'lang';
-
-	override getAttributeValue(localName: 'lang'): string;
-	override getAttributeValue(localName: string): string | null;
-	override getAttributeValue<LocalName extends string>(
-		localName: LocalName
-	): ItextTranslationRootKnownAttributeValue<LocalName> {
-		const value = super.getAttributeValue(localName);
-
-		assertItextTranslationRootKnownAttributeValue(localName, value);
-
-		return value;
-	}
-}

package/src/parse/model/ItextTranslation/ItextTranslationsDefinition.ts

@@ -1,31 +0,0 @@
-import type { XFormsItextTranslationMap } from '@getodk/xpath';
-import type { EngineXPathNode } from '../../../integration/xpath/adapter/kind.ts';
-import { parseStaticDocumentFromDOMSubtree } from '../../shared/parseStaticDocumentFromDOMSubtree.ts';
-import type { XFormDOM } from '../../XFormDOM.ts';
-import { ItextTranslationDefinition } from './ItextTranslationDefinition.ts';
-import { ItextTranslationRootDefinition } from './ItextTranslationRootDefinition.ts';
-
-export class ItextTranslationsDefinition
-	extends Map<string, ItextTranslationRootDefinition>
-	implements XFormsItextTranslationMap<EngineXPathNode>
-{
-	static from(xformDOM: XFormDOM): ItextTranslationsDefinition {
-		const translationDefinitions = xformDOM.itextTranslationElements.map((element) => {
-			return parseStaticDocumentFromDOMSubtree(
-				ItextTranslationDefinition,
-				ItextTranslationRootDefinition,
-				element
-			);
-		});
-
-		return new this(translationDefinitions);
-	}
-
-	private constructor(translations: readonly ItextTranslationDefinition[]) {
-		super(
-			translations.map(({ root }) => {
-				return [root.getAttributeValue('lang'), root];
-			})
-		);
-	}
-}

package/src/parse/model/RepeatInstanceDefinition.ts

@@ -1,38 +0,0 @@
-import { NamespaceDeclarationMap } from '../../lib/names/NamespaceDeclarationMap.ts';
-import { QualifiedName } from '../../lib/names/QualifiedName.ts';
-import { RepeatElementDefinition } from '../body/RepeatElementDefinition.ts';
-import { DescendentNodeDefinition } from './DescendentNodeDefinition.ts';
-import type { ChildNodeDefinition } from './NodeDefinition.ts';
-import type { AnyRepeatRangeDefinition } from './RepeatRangeDefinition.ts';
-
-export class RepeatInstanceDefinition extends DescendentNodeDefinition<
-	'repeat-instance',
-	RepeatElementDefinition
-> {
-	readonly type = 'repeat-instance';
-
-	readonly namespaceDeclarations: NamespaceDeclarationMap;
-	readonly qualifiedName: QualifiedName;
-	readonly children: readonly ChildNodeDefinition[];
-	readonly instances = null;
-	readonly defaultValue = null;
-
-	constructor(
-		range: AnyRepeatRangeDefinition,
-		readonly node: Element
-	) {
-		const { bind, bodyElement, parent, root } = range;
-
-		super(parent, bind, bodyElement);
-
-		this.qualifiedName = new QualifiedName(node);
-		this.namespaceDeclarations = new NamespaceDeclarationMap(this);
-		this.children = root.buildSubtree(this);
-	}
-
-	toJSON() {
-		const { bind, bodyElement, parent, root, ...rest } = this;
-
-		return rest;
-	}
-}

package/src/parse/model/RepeatRangeDefinition.ts

@@ -1,98 +0,0 @@
-import { NamespaceDeclarationMap } from '../../lib/names/NamespaceDeclarationMap.ts';
-import { QualifiedName } from '../../lib/names/QualifiedName.ts';
-import type { RepeatElementDefinition } from '../body/RepeatElementDefinition.ts';
-import { RepeatCountControlExpression } from '../expression/RepeatCountControlExpression.ts';
-import type { BindDefinition } from './BindDefinition.ts';
-import { DescendentNodeDefinition } from './DescendentNodeDefinition.ts';
-import type { ParentNodeDefinition } from './NodeDefinition.ts';
-import { RepeatInstanceDefinition } from './RepeatInstanceDefinition.ts';
-import { RepeatTemplateDefinition } from './RepeatTemplateDefinition.ts';
-
-export interface ControlledRepeatRangeDefinition extends RepeatRangeDefinition {
-	readonly count: RepeatCountControlExpression;
-}
-
-export interface UncontrolledRepeatRangeDefinition extends RepeatRangeDefinition {
-	readonly count: null;
-}
-
-// prettier-ignore
-export type AnyRepeatRangeDefinition =
-	| ControlledRepeatRangeDefinition
-	| UncontrolledRepeatRangeDefinition;
-
-type AssertRepeatRangeDefinitionUnion = (
-	definition: RepeatRangeDefinition
-) => asserts definition is AnyRepeatRangeDefinition;
-
-const assertRepeatRangeDefinitionUnion: AssertRepeatRangeDefinitionUnion = (_definition) => {
-	// Intentional no-op, used to guide the type checker. Implementation would
-	// check _definition.count == null || _definition.count != null, which is
-	// tautologically true!
-};
-
-export class RepeatRangeDefinition extends DescendentNodeDefinition<
-	'repeat-range',
-	RepeatElementDefinition
-> {
-	static from(
-		parent: ParentNodeDefinition,
-		bind: BindDefinition,
-		bodyElement: RepeatElementDefinition,
-		modelNodes: readonly [Element, ...Element[]]
-	): AnyRepeatRangeDefinition {
-		const definition = new this(parent, bind, bodyElement, modelNodes);
-
-		assertRepeatRangeDefinitionUnion(definition);
-
-		return definition;
-	}
-
-	readonly type = 'repeat-range';
-
-	readonly template: RepeatTemplateDefinition;
-	readonly children = null;
-	readonly instances: RepeatInstanceDefinition[];
-	readonly count: RepeatCountControlExpression | null;
-
-	readonly node = null;
-	readonly namespaceDeclarations: NamespaceDeclarationMap;
-	readonly qualifiedName: QualifiedName;
-	readonly defaultValue = null;
-
-	private constructor(
-		parent: ParentNodeDefinition,
-		bind: BindDefinition,
-		bodyElement: RepeatElementDefinition,
-		modelNodes: readonly [Element, ...Element[]]
-	) {
-		super(parent, bind, bodyElement);
-
-		const { template, instanceNodes } = RepeatTemplateDefinition.parseModelNodes(this, modelNodes);
-
-		this.template = template;
-		this.qualifiedName = template.qualifiedName;
-		this.namespaceDeclarations = new NamespaceDeclarationMap(this);
-		this.count = RepeatCountControlExpression.from(bodyElement, instanceNodes.length);
-
-		assertRepeatRangeDefinitionUnion(this);
-
-		this.instances = instanceNodes.map((element) => {
-			return new RepeatInstanceDefinition(this, element);
-		});
-	}
-
-	isControlled(): this is ControlledRepeatRangeDefinition {
-		return this.count != null;
-	}
-
-	isUncontrolled(): this is UncontrolledRepeatRangeDefinition {
-		return this.count == null;
-	}
-
-	toJSON() {
-		const { bind, bodyElement: groupDefinition, parent, root, ...rest } = this;
-
-		return rest;
-	}
-}

package/src/parse/model/RepeatTemplateDefinition.ts

@@ -1,149 +0,0 @@
-import { JAVAROSA_NAMESPACE_URI } from '@getodk/common/constants/xmlns.ts';
-import { NamespaceDeclarationMap } from '../../lib/names/NamespaceDeclarationMap.ts';
-import { QualifiedName } from '../../lib/names/QualifiedName.ts';
-import type { RepeatElementDefinition } from '../body/RepeatElementDefinition.ts';
-import { BindDefinition } from './BindDefinition.ts';
-import { DescendentNodeDefinition } from './DescendentNodeDefinition.ts';
-import type { ChildNodeDefinition } from './NodeDefinition.ts';
-import type { RepeatRangeDefinition } from './RepeatRangeDefinition.ts';
-
-const repeatTemplates = new WeakMap<BindDefinition, RepeatTemplateDefinition>();
-
-interface ExplicitRepeatTemplateElement extends Element {
-	getAttributeNS(namespaceURI: typeof JAVAROSA_NAMESPACE_URI, name: 'template'): string;
-	getAttributeNS(namespaceURI: string | null, name: string): string | null;
-
-	hasAttributeNS(namespaceURI: typeof JAVAROSA_NAMESPACE_URI, name: 'template'): true;
-	(namespaceURI: string | null, name: string): boolean;
-}
-
-const isExplicitRepeatTemplateElement = (
-	element: Element
-): element is ExplicitRepeatTemplateElement => {
-	return element.hasAttributeNS(JAVAROSA_NAMESPACE_URI, 'template');
-};
-
-type InstanceNodes = readonly [template: ExplicitRepeatTemplateElement, ...rest: Element[]];
-
-interface LeafNode extends Element {
-	readonly childElementCount: 0;
-}
-
-const isLeafNode = (element: Element): element is LeafNode => {
-	return element.childElementCount === 0;
-};
-
-const clearLeafNodes = <T extends Element>(element: T): T => {
-	if (isLeafNode(element)) {
-		element.textContent = '';
-	} else {
-		for (const child of element.children) {
-			clearLeafNodes(child);
-		}
-	}
-
-	return element;
-};
-
-const getOrCreateTemplateElement = (element: Element): ExplicitRepeatTemplateElement => {
-	if (isExplicitRepeatTemplateElement(element)) {
-		return element;
-	}
-
-	const clone = element.cloneNode(true) as Element;
-	clone.setAttributeNS(JAVAROSA_NAMESPACE_URI, 'template', '');
-
-	return clearLeafNodes(clone as ExplicitRepeatTemplateElement);
-};
-
-// TODO: under what circumstances should a default instance be created, and is
-// this the appropriate place for that?
-const splitInstanceNodes = (modelNodes: readonly [Element, ...Element[]]): InstanceNodes => {
-	const [first, ...rest] = modelNodes;
-	const template = getOrCreateTemplateElement(first);
-
-	if (template === first) {
-		return [template, ...rest];
-	}
-
-	return [template, ...modelNodes];
-};
-
-interface ParsedRepeatNodes {
-	readonly template: RepeatTemplateDefinition;
-	readonly instanceNodes: readonly Element[];
-}
-
-export class RepeatTemplateDefinition extends DescendentNodeDefinition<
-	'repeat-template',
-	RepeatElementDefinition
-> {
-	static parseModelNodes(
-		range: RepeatRangeDefinition,
-		modelNodes: readonly [Element, ...Element[]]
-	): ParsedRepeatNodes {
-		const { bind } = range;
-
-		let template = repeatTemplates.get(bind);
-		let instanceNodes: readonly Element[];
-
-		if (template == null) {
-			const [templateNode, ...rest] = splitInstanceNodes(modelNodes);
-
-			instanceNodes = rest;
-			template = new this(range, templateNode);
-		} else {
-			// TODO: this is under the assumption that for any depth > 1, if a
-			// template has already been defined for the given form definition, any
-			// subsequent nodes matching the repeat's nodeset are implicitly default
-			// instances. Is this right?
-			const duplicateTemplate = modelNodes.find((node) =>
-				node.hasAttributeNS(JAVAROSA_NAMESPACE_URI, 'template')
-			);
-
-			if (duplicateTemplate != null) {
-				throw new Error(`Multiple explicit templates defined for ${bind.nodeset}`);
-			}
-
-			instanceNodes = modelNodes;
-		}
-
-		return {
-			template,
-			instanceNodes,
-		};
-	}
-
-	readonly type = 'repeat-template';
-
-	readonly node: Element;
-	readonly namespaceDeclarations: NamespaceDeclarationMap;
-	readonly qualifiedName: QualifiedName;
-	readonly children: readonly ChildNodeDefinition[];
-	readonly instances = null;
-	readonly defaultValue = null;
-
-	protected constructor(
-		range: RepeatRangeDefinition,
-		protected readonly templateNode: ExplicitRepeatTemplateElement
-	) {
-		const { bind, bodyElement, parent, root } = range;
-
-		super(parent, bind, bodyElement);
-
-		const node = templateNode.cloneNode(true) as Element;
-
-		node.removeAttributeNS(JAVAROSA_NAMESPACE_URI, 'template');
-
-		this.node = node;
-		this.qualifiedName = new QualifiedName(node);
-		this.namespaceDeclarations = new NamespaceDeclarationMap(this);
-		this.children = root.buildSubtree(this);
-	}
-
-	toJSON() {
-		const { bind, bodyElement, parent, root, ...rest } = this;
-
-		return rest;
-	}
-}

package/src/parse/model/SecondaryInstance/SecondaryInstanceDefinition.ts

@@ -1,4 +0,0 @@
-import { StaticDocument } from '../../../integration/xpath/static-dom/StaticDocument.ts';
-import { SecondaryInstanceRootDefinition } from './SecondaryInstanceRootDefinition.ts';
-
-export class SecondaryInstanceDefinition extends StaticDocument<SecondaryInstanceRootDefinition> {}

package/src/parse/model/SecondaryInstance/SecondaryInstanceRootDefinition.ts

@@ -1,12 +0,0 @@
-import type { XFormsSecondaryInstanceElement } from '@getodk/xpath';
-import { XFORMS_KNOWN_ATTRIBUTE, XFORMS_LOCAL_NAME } from '@getodk/xpath';
-import { StaticElement } from '../../../integration/xpath/static-dom/StaticElement.ts';
-import type { SecondaryInstanceDefinition } from './SecondaryInstanceDefinition.ts';
-
-export class SecondaryInstanceRootDefinition
-	extends StaticElement<SecondaryInstanceDefinition>
-	implements XFormsSecondaryInstanceElement<StaticElement>
-{
-	override readonly [XFORMS_LOCAL_NAME] = 'instance';
-	override readonly [XFORMS_KNOWN_ATTRIBUTE] = 'id';
-}