@getodk/xforms-engine 0.6.0 → 0.7.0

package/src/lib/client-reactivity/submission/prepareSubmission.ts

@@ -1,172 +0,0 @@
-import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
-import {
-	SUBMISSION_INSTANCE_FILE_NAME,
-	SUBMISSION_INSTANCE_FILE_TYPE,
-} from '../../../client/constants.ts';
-import type { SubmissionData } from '../../../client/submission/SubmissionData.ts';
-import type { SubmissionDefinition } from '../../../client/submission/SubmissionDefinition.ts';
-import type { SubmissionInstanceFile } from '../../../client/submission/SubmissionInstanceFile.ts';
-import type { SubmissionChunkedType } from '../../../client/submission/SubmissionOptions.ts';
-import type { SubmissionResult } from '../../../client/submission/SubmissionResult.ts';
-import type { DescendantNodeViolationReference } from '../../../client/validation.ts';
-import type { ClientReactiveSubmittableInstance } from '../../../instance/internal-api/submission/ClientReactiveSubmittableInstance.ts';
-
-class InstanceFile extends File implements SubmissionInstanceFile {
-	override readonly name = SUBMISSION_INSTANCE_FILE_NAME;
-	override readonly type = SUBMISSION_INSTANCE_FILE_TYPE;
-
-	constructor(instanceRoot: ClientReactiveSubmittableInstance) {
-		const { submissionXML } = instanceRoot.submissionState;
-
-		super([submissionXML], SUBMISSION_INSTANCE_FILE_NAME, {
-			type: SUBMISSION_INSTANCE_FILE_TYPE,
-		});
-	}
-}
-
-type AssertSubmissionData = (data: FormData) => asserts data is SubmissionData;
-
-const assertSubmissionData: AssertSubmissionData = (data) => {
-	const instanceFile = data.get(SUBMISSION_INSTANCE_FILE_NAME);
-
-	if (!(instanceFile instanceof InstanceFile)) {
-		throw new Error(`Invalid SubmissionData`);
-	}
-};
-
-class InstanceSubmissionData extends FormData {
-	static from(instanceFile: InstanceFile, attachments: readonly File[]): SubmissionData {
-		const data = new this(instanceFile, attachments);
-
-		assertSubmissionData(data);
-
-		return data;
-	}
-
-	private constructor(
-		readonly instanceFile: InstanceFile,
-		readonly attachments: readonly File[]
-	) {
-		super();
-
-		this.set(SUBMISSION_INSTANCE_FILE_NAME, instanceFile);
-
-		attachments.forEach((attachment) => {
-			const { name } = attachment;
-
-			if (name === SUBMISSION_INSTANCE_FILE_NAME && attachment !== instanceFile) {
-				throw new Error(
-					`Failed to add conflicting attachment with name ${SUBMISSION_INSTANCE_FILE_NAME}`
-				);
-			}
-
-			this.set(name, attachment);
-		});
-	}
-}
-
-interface PendingValidation {
-	readonly status: 'pending';
-	readonly violations: readonly DescendantNodeViolationReference[];
-}
-
-interface ReadyValidation {
-	readonly status: 'ready';
-	readonly violations: null;
-}
-
-type SubmissionInstanceStateValidation = PendingValidation | ReadyValidation;
-
-const validateSubmission = (
-	instanceRoot: ClientReactiveSubmittableInstance
-): SubmissionInstanceStateValidation => {
-	const { violations } = instanceRoot.validationState;
-
-	if (violations.length === 0) {
-		return {
-			status: 'ready',
-			violations: null,
-		};
-	}
-
-	return {
-		status: 'pending',
-		violations,
-	};
-};
-
-const monolithicSubmissionResult = (
-	validation: SubmissionInstanceStateValidation,
-	definition: SubmissionDefinition,
-	instanceFile: InstanceFile,
-	attachments: readonly File[]
-): SubmissionResult<'monolithic'> => {
-	const data = InstanceSubmissionData.from(instanceFile, attachments);
-
-	return {
-		...validation,
-		definition,
-		data,
-	};
-};
-
-interface ChunkedSubmissionResultOptions {
-	readonly maxSize: number;
-}
-
-const chunkedSubmissionResult = (
-	validation: SubmissionInstanceStateValidation,
-	definition: SubmissionDefinition,
-	instanceFile: InstanceFile,
-	attachments: readonly File[],
-	options: ChunkedSubmissionResultOptions
-): SubmissionResult<'chunked'> => {
-	if (attachments.length > 0 || options.maxSize !== Infinity) {
-		throw new Error('Submission chunking pending implementation');
-	}
-
-	const data = InstanceSubmissionData.from(instanceFile, attachments);
-
-	return {
-		...validation,
-		definition,
-		data: [data],
-	};
-};
-
-export interface PrepeareSubmissionOptions<ChunkedType extends SubmissionChunkedType> {
-	readonly chunked: ChunkedType;
-	readonly maxSize: number;
-}
-
-export const prepareSubmission = <ChunkedType extends SubmissionChunkedType>(
-	instanceRoot: ClientReactiveSubmittableInstance,
-	options: PrepeareSubmissionOptions<ChunkedType>
-): SubmissionResult<ChunkedType> => {
-	const validation = validateSubmission(instanceRoot);
-	const definition = instanceRoot.definition.submission;
-	const instanceFile = new InstanceFile(instanceRoot);
-	const attachments: readonly File[] = [];
-
-	switch (options.chunked) {
-		case 'chunked':
-			return chunkedSubmissionResult(
-				validation,
-				definition,
-				instanceFile,
-				attachments,
-				options
-			) satisfies SubmissionResult<'chunked'> as SubmissionResult<ChunkedType>;
-
-		case 'monolithic':
-			return monolithicSubmissionResult(
-				validation,
-				definition,
-				instanceFile,
-				attachments
-			) satisfies SubmissionResult<'monolithic'> as SubmissionResult<ChunkedType>;
-
-		default:
-			throw new UnreachableError(options.chunked);
-	}
-};

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;
-	}
-}