@getodk/xforms-engine 0.4.0 → 0.6.0

package/src/instance/RankControl.ts

@@ -0,0 +1,199 @@
+import { XPathNodeKindKey } from '@getodk/xpath';
+import type { Accessor } from 'solid-js';
+import { createMemo } from 'solid-js';
+import type { RankDefinition, RankItem, RankNode, RankValueOptions } from '../client/RankNode.ts';
+import type { TextRange } from '../client/TextRange.ts';
+import type { XFormsXPathElement } from '../integration/xpath/adapter/XFormsXPathNode.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 { Root } from './Root.ts';
+import type { ValueNodeStateSpec } from './abstract/ValueNode.ts';
+import { ValueNode } from './abstract/ValueNode.ts';
+import type { GeneralParentNode } from './hierarchy.ts';
+import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
+import type { ValidationContext } from './internal-api/ValidationContext.ts';
+import type { ClientReactiveSubmittableValueNode } from './internal-api/submission/ClientReactiveSubmittableValueNode.ts';
+import { MultipleValueItemCodec } from '../lib/codecs/items/MultipleValueItemCodec.ts';
+import { sharedValueCodecs } from '../lib/codecs/getSharedValueCodec.ts';
+import { createItemCollection } from '../lib/reactivity/createItemCollection.ts';
+import type { UnknownAppearanceDefinition } from '../parse/body/appearance/unknownAppearanceParser.ts';
+import type { ValueType } from '../client/ValueType.ts';
+import { RankMissingValueError } from '../error/RankMissingValueError.ts';
+import { RankValueTypeError } from '../error/RankValueTypeError.ts';
+
+export type AnyRankDefinition = {
+	[V in ValueType]: RankDefinition<V>;
+}[ValueType];
+
+type AssertRankNodeDefinition = (
+	definition: AnyRankDefinition
+) => asserts definition is RankDefinition<'string'>;
+
+const assertRankNodeDefinition: AssertRankNodeDefinition = (definition) => {
+	if (definition.valueType !== 'string') {
+		throw new RankValueTypeError(definition);
+	}
+};
+
+type RankItemMap = ReadonlyMap<string, RankItem>;
+
+interface RankControlStateSpec extends ValueNodeStateSpec<readonly string[]> {
+	readonly label: Accessor<TextRange<'label'> | null>;
+	readonly hint: Accessor<TextRange<'hint'> | null>;
+	readonly valueOptions: Accessor<RankValueOptions>;
+}
+
+/**
+ * @ToDo We currently represent a blank value for `<odk:rank>` as an empty array.
+ * This is ambiguous, and likely to change.
+ *
+ * @see {@link https://github.com/getodk/web-forms/issues/295}
+ */
+type TempBlankValueState = readonly [];
+const isBlankValueState = (values: readonly string[]): values is TempBlankValueState => {
+	return values.length === 0;
+};
+
+export class RankControl
+	extends ValueNode<'string', RankDefinition<'string'>, readonly string[], readonly string[]>
+	implements
+		RankNode,
+		XFormsXPathElement,
+		EvaluationContext,
+		ValidationContext,
+		ClientReactiveSubmittableValueNode
+{
+	static from(parent: GeneralParentNode, definition: RankDefinition): RankControl;
+	static from(parent: GeneralParentNode, definition: AnyRankDefinition): RankControl {
+		assertRankNodeDefinition(definition);
+		return new this(parent, definition);
+	}
+
+	private readonly mapOptionsByValue: Accessor<RankItemMap>;
+
+	protected override readonly getInstanceValue: Accessor<string>;
+
+	// XFormsXPathElement
+	override readonly [XPathNodeKindKey] = 'element';
+
+	// InstanceNode
+	protected readonly state: SharedNodeState<RankControlStateSpec>;
+	protected readonly engineState: EngineState<RankControlStateSpec>;
+
+	// RankNode
+	readonly nodeType = 'rank';
+	readonly appearances: UnknownAppearanceDefinition;
+	readonly nodeOptions = null;
+	readonly currentState: CurrentState<RankControlStateSpec>;
+
+	private constructor(parent: GeneralParentNode, definition: RankDefinition<'string'>) {
+		const codec = new MultipleValueItemCodec(sharedValueCodecs.string);
+		super(parent, definition, codec);
+
+		this.appearances = definition.bodyElement.appearances;
+
+		const valueOptions = createItemCollection(this);
+		const mapOptionsByValue: Accessor<RankItemMap> = this.scope.runTask(() => {
+			return createMemo(() => {
+				return new Map(valueOptions().map((item) => [item.value, item]));
+			});
+		});
+
+		this.mapOptionsByValue = mapOptionsByValue;
+
+		const baseValueState = this.valueState;
+		const [baseGetValue, setValue] = baseValueState;
+
+		/**
+		 * @ToDo As new value options become available, they're not yet in the
+		 * `currentValues` state. This appends them. We intend to change this
+		 * behavior, likely clearing the previous state instead.
+		 *
+		 * However, there's an open question about what we should do when a filter
+		 * change **only removes values**.
+		 */
+		const getValue = this.scope.runTask(() => {
+			return createMemo(() => {
+				const options = valueOptions();
+				const values = baseGetValue();
+
+				if (isBlankValueState(values)) {
+					return values;
+				}
+
+				const optionValues = new Set(options.map((option) => option.value));
+
+				/**
+				 * @see {@link getValue} ToDo paragraph 2.
+				 */
+				const currentValues = values.filter((value) => optionValues.has(value));
+
+				return Array.from(
+					new Set([
+						...currentValues,
+						/**
+						 * @see {@link getValue} ToDo paragraph 1.
+						 */
+						...optionValues,
+					])
+				);
+			});
+		});
+		const valueState: SimpleAtomicState<readonly string[]> = [getValue, setValue];
+
+		this.getInstanceValue = this.scope.runTask(() => {
+			return createMemo(() => codec.encodeValue(getValue()));
+		});
+
+		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,
+				value: valueState,
+				instanceValue: this.getInstanceValue,
+			},
+			sharedStateOptions
+		);
+
+		this.state = state;
+		this.engineState = state.engineState;
+		this.currentState = state.currentState;
+	}
+
+	getValueLabel(value: string): TextRange<'item-label'> | null {
+		const valueOption = this.currentState.valueOptions.find((item) => item.value === value);
+		return valueOption?.label ?? null;
+	}
+
+	setValues(valuesInOrder: readonly string[]): Root {
+		if (isBlankValueState(valuesInOrder)) {
+			this.setValueState(valuesInOrder);
+			return this.root;
+		}
+
+		const sourceValues: string[] = Array.from(this.mapOptionsByValue().keys());
+		const hasAllValues = sourceValues.every((sourceValue) => valuesInOrder.includes(sourceValue));
+		if (!hasAllValues) {
+			throw new RankMissingValueError('There are missing options. Rank should have all options.');
+		}
+
+		this.setValueState(valuesInOrder);
+		return this.root;
+	}
+}

package/src/instance/Root.ts

@@ -1,9 +1,18 @@
-import type { XFormsXPathEvaluator } from '@getodk/xpath';
-import type { Accessor, Signal } from 'solid-js';
-import { createSignal } from 'solid-js';
+import { XPathNodeKindKey } from '@getodk/xpath';
+import type { Accessor } from 'solid-js';
 import type { ActiveLanguage, FormLanguage, FormLanguages } from '../client/FormLanguage.ts';
+import type { FormNodeID } from '../client/identity.ts';
 import type { RootNode } from '../client/RootNode.ts';
+import type { SubmissionDefinition } from '../client/submission/SubmissionDefinition.ts';
+import type {
+	SubmissionChunkedType,
+	SubmissionOptions,
+} from '../client/submission/SubmissionOptions.ts';
+import type { SubmissionResult } from '../client/submission/SubmissionResult.ts';
+import type { SubmissionState } from '../client/submission/SubmissionState.ts';
 import type { AncestorNodeValidationState } from '../client/validation.ts';
+import type { XFormsXPathElement } from '../integration/xpath/adapter/XFormsXPathNode.ts';
+import { createRootSubmissionState } from '../lib/client-reactivity/submission/createRootSubmissionState.ts';
 import type { ChildrenState } from '../lib/reactivity/createChildrenState.ts';
 import { createChildrenState } from '../lib/reactivity/createChildrenState.ts';
 import type { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
@@ -15,146 +24,88 @@ import { createSharedNodeState } from '../lib/reactivity/node-state/createShared
 import { createAggregatedViolations } from '../lib/reactivity/validation/createAggregatedViolations.ts';
 import type { BodyClassList } from '../parse/body/BodyDefinition.ts';
 import type { RootDefinition } from '../parse/model/RootDefinition.ts';
-import type { XFormDOM } from '../parse/XFormDOM.ts';
-import { InstanceNode } from './abstract/InstanceNode.ts';
+import { DescendantNode } from './abstract/DescendantNode.ts';
 import { buildChildren } from './children.ts';
 import type { GeneralChildNode } from './hierarchy.ts';
-import type { NodeID } from './identity.ts';
-import type { EvaluationContext, EvaluationContextRoot } from './internal-api/EvaluationContext.ts';
-import type { InstanceConfig } from './internal-api/InstanceConfig.ts';
-import type { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
+import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
+import type { ClientReactiveSubmittableParentNode } from './internal-api/submission/ClientReactiveSubmittableParentNode.ts';
 import type { TranslationContext } from './internal-api/TranslationContext.ts';
+import type { PrimaryInstance } from './PrimaryInstance.ts';
 
 interface RootStateSpec {
-	readonly reference: string;
-	readonly readonly: boolean;
-	readonly relevant: boolean;
-	readonly required: boolean;
+	readonly reference: Accessor<string>;
+	readonly readonly: Accessor<boolean>;
+	readonly relevant: Accessor<boolean>;
+	readonly required: Accessor<boolean>;
 	readonly label: null;
 	readonly hint: null;
-	readonly children: Accessor<readonly NodeID[]>;
+	readonly children: Accessor<readonly FormNodeID[]>;
 	readonly valueOptions: null;
 	readonly value: null;
 
 	// Root-specific
-	readonly activeLanguage: Signal<ActiveLanguage>;
+	readonly activeLanguage: Accessor<ActiveLanguage>;
 }
 
-// Subset of types expected from evaluator
-interface ItextTranslations {
-	getActiveLanguage(): string | null;
-	getLanguages(): readonly string[];
-}
-
-interface InitialLanguageState {
-	readonly defaultLanguage: ActiveLanguage;
-	readonly languages: FormLanguages;
-}
-
-// TODO: it's really very silly that the XPath evaluator is the current
-// definitional source of truth for translation stuff... even though it currently makes sense that that's where it's first derived.
-const getInitialLanguageState = (translations: ItextTranslations): InitialLanguageState => {
-	const activeLanguageName = translations.getActiveLanguage();
-
-	if (activeLanguageName == null) {
-		const defaultLanguage: ActiveLanguage = {
-			isSyntheticDefault: true,
-			language: '',
-		};
-		const languages = [defaultLanguage] satisfies FormLanguages;
-
-		return {
-			defaultLanguage,
-			languages,
-		};
-	}
-
-	const languageNames = translations.getLanguages();
-
-	const inactiveLanguages = languageNames
-		.filter((languageName) => {
-			return languageName !== activeLanguageName;
-		})
-		.map((language): FormLanguage => {
-			return { language };
-		});
-
-	const languages = [
-		{ language: activeLanguageName } satisfies FormLanguage,
-
-		...inactiveLanguages,
-	] satisfies FormLanguages;
-	const [defaultLanguage] = languages;
-
-	return {
-		defaultLanguage,
-		languages,
-	};
-};
-
 export class Root
-	extends InstanceNode<RootDefinition, RootStateSpec, GeneralChildNode>
+	extends DescendantNode<RootDefinition, RootStateSpec, PrimaryInstance, GeneralChildNode>
 	implements
 		RootNode,
+		XFormsXPathElement,
 		EvaluationContext,
-		EvaluationContextRoot,
-		SubscribableDependency,
-		TranslationContext
+		TranslationContext,
+		ClientReactiveSubmittableParentNode<GeneralChildNode>
 {
 	private readonly childrenState: ChildrenState<GeneralChildNode>;
 
-	// InstanceNode
-	readonly hasReadonlyAncestor = () => false;
-	readonly isReadonly = () => false;
-	readonly hasNonRelevantAncestor = () => false;
-	readonly isRelevant = () => true;
+	// XFormsXPathElement
+	override readonly [XPathNodeKindKey] = 'element';
+
+	// DescendantNode
 	protected readonly state: SharedNodeState<RootStateSpec>;
 	protected readonly engineState: EngineState<RootStateSpec>;
 
+	override readonly hasReadonlyAncestor = () => false;
+	override readonly isSelfReadonly = () => false;
+	override readonly isReadonly = () => false;
+	override readonly hasNonRelevantAncestor = () => false;
+	override readonly isSelfRelevant = () => true;
+	override readonly isRelevant = () => true;
+	override readonly isRequired = () => false;
+
 	// RootNode
 	readonly nodeType = 'root';
 	readonly appearances = null;
+	readonly nodeOptions = null;
 	readonly classes: BodyClassList;
 	readonly currentState: MaterializedChildren<CurrentState<RootStateSpec>, GeneralChildNode>;
 	readonly validationState: AncestorNodeValidationState;
+	readonly submissionState: SubmissionState;
 
-	protected readonly instanceDOM: XFormDOM;
-
-	// BaseNode
-	readonly root = this;
-
-	// EvaluationContext
-	readonly evaluator: XFormsXPathEvaluator;
-
-	readonly contextNode: Element;
+	// ClientReactiveSubmittableInstance
+	get submissionDefinition(): SubmissionDefinition {
+		return this.definition.submission;
+	}
 
 	// RootNode
-	override readonly parent = null;
-
 	readonly languages: FormLanguages;
 
-	// TranslationContext
-	get activeLanguage(): ActiveLanguage {
-		return this.engineState.activeLanguage;
-	}
-
-	constructor(xformDOM: XFormDOM, definition: RootDefinition, engineConfig: InstanceConfig) {
-		const reference = definition.nodeset;
+	constructor(parent: PrimaryInstance) {
+		const { definition } = parent;
+		const { nodeset: reference } = definition;
+		const computeReference: Accessor<string> = () => reference;
 
-		super(engineConfig, null, definition, {
-			computeReference: () => reference,
+		super(parent, definition, {
+			computeReference,
 		});
 
-		this.classes = definition.classes;
+		this.classes = parent.classes;
 
 		const childrenState = createChildrenState<Root, GeneralChildNode>(this);
 
 		this.childrenState = childrenState;
+		this.languages = parent.languages;
 
-		const instanceDOM = xformDOM.createInstance();
-		const evaluator = instanceDOM.primaryInstanceEvaluator;
-		const { translations } = evaluator;
-		const { defaultLanguage, languages } = getInitialLanguageState(translations);
 		const sharedStateOptions = {
 			clientStateFactory: this.engineConfig.stateFactory,
 		};
@@ -162,13 +113,13 @@ export class Root
 		const state = createSharedNodeState(
 			this.scope,
 			{
-				activeLanguage: createSignal<ActiveLanguage>(defaultLanguage),
-				reference,
+				activeLanguage: parent.getActiveLanguage,
+				reference: computeReference,
 				label: null,
 				hint: null,
-				readonly: false,
-				relevant: true,
-				required: false,
+				readonly: () => false,
+				relevant: () => true,
+				required: () => false,
 				valueOptions: null,
 				value: null,
 				children: childrenState.childIds,
@@ -184,17 +135,9 @@ export class Root
 			childrenState
 		);
 
-		const contextNode = instanceDOM.xformDocument.createElement(definition.nodeName);
-
-		instanceDOM.primaryInstanceRoot.replaceWith(contextNode);
-
-		this.evaluator = evaluator;
-		this.contextNode = contextNode;
-		this.instanceDOM = instanceDOM;
-		this.languages = languages;
-
 		childrenState.setChildren(buildChildren(this));
 		this.validationState = createAggregatedViolations(this, sharedStateOptions);
+		this.submissionState = createRootSubmissionState(this);
 	}
 
 	getChildren(): readonly GeneralChildNode[] {
@@ -203,28 +146,14 @@ export class Root
 
 	// RootNode
 	setLanguage(language: FormLanguage): Root {
-		const activeLanguage = this.languages.find((formLanguage) => {
-			return formLanguage.language === language.language;
-		});
-
-		if (activeLanguage == null) {
-			throw new Error(`Language "${language.language}" not available`);
-		}
-
-		this.evaluator.translations.setActiveLanguage(activeLanguage.language);
-		this.state.setProperty('activeLanguage', activeLanguage);
+		this.rootDocument.setLanguage(language);
 
 		return this;
 	}
 
-	// SubscribableDependency
-	override subscribe(): void {
-		super.subscribe();
-
-		// TODO: typescript-eslint is right to object to this! We should _at least_
-		// make internal reactive reads obvious, i.e. function calls.
-		//
-		// eslint-disable-next-line @typescript-eslint/no-unused-expressions -- read == subscribe
-		this.engineState.activeLanguage;
+	prepareSubmission<ChunkedType extends SubmissionChunkedType = 'monolithic'>(
+		options?: SubmissionOptions<ChunkedType>
+	): Promise<SubmissionResult<ChunkedType>> {
+		return this.rootDocument.prepareSubmission(options);
 	}
 }