@getodk/xforms-engine 0.5.0 → 0.7.0

package/src/instance/children/buildChildren.ts

@@ -0,0 +1,206 @@
+import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
+import type { GroupDefinition } from '../../client/GroupNode.ts';
+import type { InputDefinition } from '../../client/InputNode.ts';
+import type { ModelValueDefinition } from '../../client/ModelValueNode.ts';
+import type { RankDefinition } from '../../client/RankNode.ts';
+import type { SelectDefinition } from '../../client/SelectNode.ts';
+import type { SubtreeDefinition } from '../../client/SubtreeNode.ts';
+import type { TriggerNodeDefinition } from '../../client/TriggerNode.ts';
+import type { UploadNodeDefinition } from '../../client/unsupported/UploadNode.ts';
+import { ErrorProductionDesignPendingError } from '../../error/ErrorProductionDesignPendingError.ts';
+import type { LeafNodeDefinition } from '../../parse/model/LeafNodeDefinition.ts';
+import { NoteNodeDefinition } from '../../parse/model/NoteNodeDefinition.ts';
+import type {
+	AnyRangeNodeDefinition,
+	RangeLeafNodeDefinition,
+} from '../../parse/model/RangeNodeDefinition.ts';
+import { RangeNodeDefinition } from '../../parse/model/RangeNodeDefinition.ts';
+import type { SubtreeDefinition as ModelSubtreeDefinition } from '../../parse/model/SubtreeDefinition.ts';
+import { Group } from '../Group.ts';
+import type { GeneralChildNode, GeneralParentNode } from '../hierarchy.ts';
+import { InputControl } from '../InputControl.ts';
+import { ModelValue } from '../ModelValue.ts';
+import { Note } from '../Note.ts';
+import { RangeControl } from '../RangeControl.ts';
+import { RankControl } from '../RankControl.ts';
+import { RepeatRangeControlled } from '../repeat/RepeatRangeControlled.ts';
+import { RepeatRangeUncontrolled } from '../repeat/RepeatRangeUncontrolled.ts';
+import { SelectControl } from '../SelectControl.ts';
+import { Subtree } from '../Subtree.ts';
+import { TriggerControl } from '../TriggerControl.ts';
+import { UploadControl } from '../unsupported/UploadControl.ts';
+import { childrenInitOptions } from './childrenInitOptions.ts';
+
+const isSubtreeDefinition = (
+	definition: ModelSubtreeDefinition
+): definition is SubtreeDefinition => {
+	return definition.bodyElement == null;
+};
+
+// prettier-ignore
+type AnyUnsupportedControlDefinition = UploadNodeDefinition;
+
+// prettier-ignore
+type ControlNodeDefinition =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| InputDefinition
+	| RangeLeafNodeDefinition
+	| SelectDefinition
+	| RankDefinition
+	| TriggerNodeDefinition
+	| AnyUnsupportedControlDefinition;
+
+type AnyLeafNodeDefinition = ControlNodeDefinition | ModelValueDefinition;
+
+const isModelValueDefinition = (
+	definition: LeafNodeDefinition
+): definition is ModelValueDefinition => {
+	return definition.bodyElement == null;
+};
+
+const isInputDefinition = (definition: ControlNodeDefinition): definition is InputDefinition => {
+	return definition.bodyElement.type === 'input';
+};
+
+const isSelectDefinition = (definition: ControlNodeDefinition): definition is SelectDefinition => {
+	return definition.bodyElement.type === 'select' || definition.bodyElement.type === 'select1';
+};
+
+const isRankDefinition = (definition: ControlNodeDefinition): definition is RankDefinition => {
+	return definition.bodyElement.type === 'rank';
+};
+
+const isRangeLeafNodeDefinition = (
+	definition: ControlNodeDefinition
+): definition is RangeLeafNodeDefinition => {
+	return definition.bodyElement.type === 'range';
+};
+
+type AssertRangeNodeDefinition = (
+	definition: RangeLeafNodeDefinition
+) => asserts definition is AnyRangeNodeDefinition;
+
+/**
+ * We need some way to narrow the base {@link RangeLeafNodeDefinition} type to
+ * {@link RankNodeDefinition} type.
+ *
+ * At time of writing, we know there is no code path to produce the broader
+ * type, but appeasing the type checker for it will help guard against
+ * introducing one. (And it would have caught exactly such a mistake in this
+ * phase of development, where a more optimistic type cast did not.)
+ *
+ * An `instanceof` check is appropriate because the narrower type refines all of
+ * the following:
+ *
+ * - `valueType` is a subset of the full range of
+ *   {@link ValueType | specified value types} (only `int` or `decimal` are
+ *   supported for range controls)
+ *
+ * - addition of range-specific properties: `min`, `max`, `step`
+ */
+const assertRangeNodeDefinition: AssertRangeNodeDefinition = (definition) => {
+	if (definition instanceof RangeNodeDefinition) {
+		return;
+	}
+
+	/**
+	 * At time of writing we know there is no code path producing this
+	 * case, but appeasing the type checker for it now will guard against
+	 * it happening mistakenly in any future refactoring. (Hint: it
+	 * occurred during some refactoring that arrived here, which is why
+	 * this isn't a type cast!)
+	 */
+	throw new ErrorProductionDesignPendingError(
+		`Invalid <range> definition with value type: ${definition.valueType}`
+	);
+};
+
+const isTriggerNodeDefinition = (
+	definition: ControlNodeDefinition
+): definition is TriggerNodeDefinition => {
+	return definition.bodyElement.type === 'trigger';
+};
+
+const isUploadNodeDefinition = (
+	definition: ControlNodeDefinition
+): definition is UploadNodeDefinition => {
+	return definition.bodyElement.type === 'upload';
+};
+
+export const buildChildren = (parent: GeneralParentNode): GeneralChildNode[] => {
+	const { children } = childrenInitOptions(parent);
+
+	return children.map(({ instanceNodes, definition }): GeneralChildNode => {
+		const [instanceNode = null] = instanceNodes;
+
+		switch (definition.type) {
+			case 'subtree': {
+				if (isSubtreeDefinition(definition)) {
+					return new Subtree(parent, instanceNode, definition);
+				}
+
+				// TODO: it'd be good to be able to do without this type assertion. The
+				// only distinction between the types is whether `bodyElement` is
+				// `null`, but for some reason that's insufficient to narrow the union.
+				return new Group(parent, instanceNode, definition as GroupDefinition);
+			}
+
+			case 'repeat': {
+				if (definition.isControlled()) {
+					return new RepeatRangeControlled(parent, instanceNodes, definition);
+				}
+
+				return new RepeatRangeUncontrolled(parent, instanceNodes, definition);
+			}
+
+			case 'leaf-node': {
+				if (instanceNode != null && !instanceNode.isLeafElement()) {
+					throw new ErrorProductionDesignPendingError();
+				}
+
+				if (definition instanceof NoteNodeDefinition) {
+					return new Note(parent, instanceNode, definition);
+				}
+
+				// More specific type helps with narrowing below
+				const leafChild: AnyLeafNodeDefinition = definition;
+
+				if (isModelValueDefinition(leafChild)) {
+					return ModelValue.from(parent, instanceNode, leafChild);
+				}
+
+				if (isInputDefinition(leafChild)) {
+					return InputControl.from(parent, instanceNode, leafChild);
+				}
+
+				if (isSelectDefinition(leafChild)) {
+					return SelectControl.from(parent, instanceNode, leafChild);
+				}
+
+				if (isRankDefinition(leafChild)) {
+					return RankControl.from(parent, instanceNode, leafChild);
+				}
+
+				if (isTriggerNodeDefinition(leafChild)) {
+					return TriggerControl.from(parent, instanceNode, leafChild);
+				}
+
+				if (isRangeLeafNodeDefinition(leafChild)) {
+					assertRangeNodeDefinition(leafChild);
+
+					return RangeControl.from(parent, instanceNode, leafChild);
+				}
+
+				if (isUploadNodeDefinition(leafChild)) {
+					return new UploadControl(parent, instanceNode, leafChild);
+				}
+
+				throw new UnreachableError(leafChild);
+			}
+
+			default: {
+				throw new UnreachableError(definition);
+			}
+		}
+	});
+};

package/src/instance/children/childrenInitOptions.ts

@@ -0,0 +1,117 @@
+import type { StaticDocument } from '../../integration/xpath/static-dom/StaticDocument.ts';
+import type { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
+import type { ModelDefinition } from '../../parse/model/ModelDefinition.ts';
+import type {
+	AnyNodeDefinition,
+	ChildNodeDefinition,
+	NodeDefinition,
+} from '../../parse/model/NodeDefinition.ts';
+import type { InstanceNode } from '../abstract/InstanceNode.ts';
+import type { GeneralParentNode } from '../hierarchy.ts';
+import type { DescendantNodeInitOptions } from './DescendantNodeInitOptions.ts';
+import { normalizeChildInitOptions } from './normalizeChildInitOptions.ts';
+
+/**
+ * Child nodesets are collected from the {@link parent}'s
+ * {@link NodeDefinition.template}, ensuring that we produce
+ * {@link InstanceNode}s for every **model-defined** node, even if a
+ * corresponding node was not serialized in a {@link parent.instanceNode}.
+ *
+ * In other words, by referencing the model-defined template, we are able to
+ * reproduce nodes which were omitted as non-relevant in a prior serialization
+ * and/or submission.
+ *
+ * @todo Since we're building an instance node's children from the nodesets of
+ * the model-defined node's children, we are _implicitly dropping_ any excess
+ * nodes from non-model instance data. That's probably the right behavior, but
+ * we may want to warn for such nodes if/when we do drop them.
+ */
+const collectModelChildNodesets = (parentTemplate: StaticElement): readonly string[] => {
+	const nodesets = parentTemplate.childElements.map(({ nodeset }) => {
+		return nodeset;
+	});
+
+	return Array.from(new Set(nodesets));
+};
+
+type InstanceNodesByNodeset = ReadonlyMap<string, readonly [StaticElement, ...StaticElement[]]>;
+
+const groupChildElementsByNodeset = (
+	parent: StaticDocument | StaticElement
+): InstanceNodesByNodeset => {
+	const result = new Map<string, [StaticElement, ...StaticElement[]]>();
+
+	for (const child of parent.childElements) {
+		const { nodeset } = child;
+		const group = result.get(nodeset);
+
+		if (group == null) {
+			result.set(nodeset, [child]);
+		} else {
+			group.push(child);
+		}
+	}
+
+	return result;
+};
+
+type AssertChildNodeDefinition = (
+	definition: AnyNodeDefinition,
+	childNodeset: string
+) => asserts definition is ChildNodeDefinition;
+
+const assertChildNodeDefinition: AssertChildNodeDefinition = (definition, childNodeset) => {
+	if (definition.type === 'root') {
+		throw new Error(`Unexpected root definition for child nodeset: ${childNodeset}`);
+	}
+};
+
+export interface ChildrenInitOptions {
+	readonly parent: GeneralParentNode;
+	readonly model: ModelDefinition;
+	readonly children: readonly DescendantNodeInitOptions[];
+}
+
+export const childrenInitOptions = (parent: GeneralParentNode): ChildrenInitOptions => {
+	const { model } = parent.rootDocument;
+	const childNodesets = collectModelChildNodesets(parent.definition.template);
+
+	let instanceChildren: InstanceNodesByNodeset | null;
+
+	if (parent.instanceNode == null) {
+		instanceChildren = null;
+	} else {
+		instanceChildren = groupChildElementsByNodeset(parent.instanceNode);
+	}
+
+	const children = childNodesets.map((childNodeset) => {
+		const definition = model.getNodeDefinition(childNodeset);
+
+		assertChildNodeDefinition(definition, childNodeset);
+
+		/**
+		 * Get children of the target nodeset from {@link parent.instanceNode}, if
+		 * that node exists, and if children with that nodeset exist.
+		 *
+		 * If either does not exist (e.g. it was omitted as non-relevant in a prior
+		 * serialization), we continue to reference model-defined templates as we
+		 * recurse down the {@link InstanceNode} subtree.
+		 *
+		 * @see {@link childNodesets}
+		 */
+		const instanceNodes = instanceChildren?.get(childNodeset) ?? [];
+
+		return {
+			childNodeset,
+			definition,
+			instanceNodes,
+		};
+	});
+	const baseResult: ChildrenInitOptions = {
+		parent,
+		model,
+		children,
+	};
+
+	return normalizeChildInitOptions(baseResult);
+};

package/src/instance/children/normalizeChildInitOptions.ts

@@ -0,0 +1,332 @@
+import {
+	OPENROSA_XFORMS_NAMESPACE_URI,
+	XFORMS_NAMESPACE_URI,
+} from '@getodk/common/constants/xmlns.ts';
+import type { GroupDefinition } from '../../client/GroupNode.ts';
+import type { SubtreeDefinition } from '../../client/SubtreeNode.ts';
+import { ErrorProductionDesignPendingError } from '../../error/ErrorProductionDesignPendingError.ts';
+import { StaticDocument } from '../../integration/xpath/static-dom/StaticDocument.ts';
+import type { StaticLeafElement } from '../../integration/xpath/static-dom/StaticElement.ts';
+import { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
+import type { NamespaceURL } from '../../lib/names/NamespaceURL.ts';
+import type { QualifiedName } from '../../lib/names/QualifiedName.ts';
+import { LeafNodeDefinition } from '../../parse/model/LeafNodeDefinition.ts';
+import type { SubtreeDefinition as ModelSubtreeDefinition } from '../../parse/model/SubtreeDefinition.ts';
+import type { XFormDOM } from '../../parse/XFormDOM.ts';
+import type { Group } from '../Group.ts';
+import type { GeneralParentNode } from '../hierarchy.ts';
+import type { PrimaryInstance } from '../PrimaryInstance.ts';
+import type { Root } from '../Root.ts';
+import type { Subtree } from '../Subtree.ts';
+import type { ChildrenInitOptions } from './childrenInitOptions.ts';
+import type { DescendantNodeInitOptions } from './DescendantNodeInitOptions.ts';
+
+const META_LOCAL_NAME = 'meta';
+const INSTANCE_ID_LOCAL_NAME = 'instanceID';
+const DEPRECATED_ID_LOCAL_NAME = 'deprecatedID';
+
+type MetaLocalName = typeof META_LOCAL_NAME;
+
+const META_NAMESPACE_URIS = [OPENROSA_XFORMS_NAMESPACE_URI, XFORMS_NAMESPACE_URI] as const;
+
+type MetaNamespaceURIValue = (typeof META_NAMESPACE_URIS)[number];
+
+interface MetaNamespaceURI extends NamespaceURL {
+	readonly href: MetaNamespaceURIValue;
+}
+
+interface MetaNamespacedName extends QualifiedName {
+	readonly namespaceURI: MetaNamespaceURI;
+}
+
+const isMetaNamespacedName = (
+	qualifiedName: QualifiedName
+): qualifiedName is MetaNamespacedName => {
+	const namespaceURI = qualifiedName.namespaceURI?.href;
+
+	return (
+		namespaceURI != null && META_NAMESPACE_URIS.includes(namespaceURI as MetaNamespaceURIValue)
+	);
+};
+
+interface MetaName extends MetaNamespacedName {
+	readonly localName: MetaLocalName;
+}
+
+const isMetaName = (qualifiedName: QualifiedName): qualifiedName is MetaName => {
+	return isMetaNamespacedName(qualifiedName) && qualifiedName.localName === META_LOCAL_NAME;
+};
+
+const isDirectRootDescendant = (parent: GeneralParentNode) => {
+	return parent.parent === parent.root;
+};
+
+interface BaseMetaDefinition {
+	readonly qualifiedName: MetaName;
+}
+
+const isBaseMetaDefinition = <T extends ModelSubtreeDefinition>(
+	definition: T
+): definition is BaseMetaDefinition & T => {
+	return isMetaName(definition.qualifiedName);
+};
+
+interface MetaSubtreeDefinition extends SubtreeDefinition {
+	readonly qualifiedName: MetaName;
+}
+
+interface MetaSubtree extends Subtree {
+	readonly parent: Root;
+	readonly definition: MetaSubtreeDefinition;
+}
+
+interface MetaGroupDefinition extends GroupDefinition {
+	readonly qualifiedName: MetaName;
+}
+
+interface MetaGroup extends Group {
+	readonly parent: Root;
+	readonly definition: MetaGroupDefinition;
+}
+
+type MetaSubroot = MetaGroup | MetaSubtree;
+
+interface MetaSubrootInitOptions extends ChildrenInitOptions {
+	readonly parent: MetaGroup | MetaSubtree;
+}
+
+const isMetaSubroot = (options: ChildrenInitOptions): options is MetaSubrootInitOptions => {
+	const { nodeType } = options.parent;
+
+	return (
+		(nodeType === 'subtree' || nodeType === 'group') &&
+		isDirectRootDescendant(options.parent) &&
+		isBaseMetaDefinition(options.parent.definition)
+	);
+};
+
+interface EditModeInstance extends PrimaryInstance {
+	readonly initializationMode: 'edit';
+}
+
+const isEditModeInstance = (
+	primaryInstance: PrimaryInstance
+): primaryInstance is EditModeInstance => {
+	return primaryInstance.initializationMode === 'edit';
+};
+
+interface EditModeInstanceDescendant {
+	readonly rootDocument: EditModeInstance;
+}
+
+type EditModeMetaSubroot = EditModeInstanceDescendant & MetaSubroot;
+
+interface EditModeMetaSubrootInitOptions extends MetaSubrootInitOptions {
+	readonly parent: EditModeMetaSubroot;
+}
+
+const isEditModeMetaSubroot = (
+	subroot: MetaSubrootInitOptions
+): subroot is EditModeMetaSubrootInitOptions => {
+	return isEditModeInstance(subroot.parent.rootDocument);
+};
+
+interface LeafNodeInitOptions extends DescendantNodeInitOptions {
+	readonly instanceNodes: readonly [StaticLeafElement];
+}
+
+const isLeafNodeInitOptions = (
+	options: DescendantNodeInitOptions
+): options is LeafNodeInitOptions => {
+	const { instanceNodes } = options;
+	const [instanceNode, ...rest] = instanceNodes;
+
+	return instanceNode != null && rest.length === 0 && instanceNode.isLeafElement();
+};
+
+type MetaLeafChildEntry = readonly [index: number, child: LeafNodeInitOptions];
+
+const findMetaLeafChild = (
+	subroot: MetaSubrootInitOptions,
+	localName: string
+): MetaLeafChildEntry | null => {
+	const metaName = subroot.parent.definition.qualifiedName satisfies MetaName;
+	const namespaceURI = metaName.namespaceURI.href satisfies MetaNamespaceURIValue;
+
+	const result = Array.from(subroot.children.entries()).find(
+		(entry): entry is [number, LeafNodeInitOptions] => {
+			const [, child] = entry;
+
+			if (!isLeafNodeInitOptions(child)) {
+				return false;
+			}
+
+			const [instanceNode] = child.instanceNodes;
+			const { qualifiedName } = instanceNode;
+
+			return (
+				qualifiedName.localName === localName && qualifiedName.namespaceURI?.href === namespaceURI
+			);
+		}
+	);
+
+	return result ?? null;
+};
+
+const getInstanceIDValue = (subroot: MetaSubrootInitOptions): string | null => {
+	const [, child = null] = findMetaLeafChild(subroot, INSTANCE_ID_LOCAL_NAME) ?? [];
+
+	if (child == null) {
+		return null;
+	}
+
+	const [instanceIDNode] = child.instanceNodes;
+
+	return instanceIDNode.value satisfies string;
+};
+
+type AssertStaticLeafElement = (element: StaticElement) => asserts element is StaticLeafElement;
+
+const assertStaticLeafElement: AssertStaticLeafElement = (element) => {
+	if (!element.isLeafElement()) {
+		throw new ErrorProductionDesignPendingError(
+			`Expected a leaf element, got a non-leaf element at nodeset: ${element.nodeset}`
+		);
+	}
+};
+
+/**
+ * @todo this name and signature are general, for the same reasons as the TODO
+ * on {@link populateDeprecatedID}.
+ */
+const buildMetaValueElement = (
+	subroot: MetaSubrootInitOptions,
+	localName: string,
+	value: string
+): StaticLeafElement => {
+	const { qualifiedName, nodeset } = subroot.parent.definition;
+	const { namespaceURI, prefix } = qualifiedName;
+	const { root } = new StaticDocument({
+		documentRoot: {
+			name: {
+				namespaceURI,
+				prefix,
+				localName,
+			},
+			children: [value],
+		},
+		nodesetPrefix: nodeset,
+	});
+
+	assertStaticLeafElement(root);
+
+	return root;
+};
+
+const buildDeprecatedIDDefinition = (
+	subroot: EditModeMetaSubrootInitOptions,
+	instanceNode: StaticLeafElement
+): LeafNodeDefinition => {
+	const nodeset = instanceNode.nodeset;
+	const bind = subroot.model.binds.getOrCreateBindDefinition(nodeset);
+
+	return new LeafNodeDefinition(subroot.parent.definition, bind, null, instanceNode);
+};
+
+const buildDeprecatedID = (
+	subroot: EditModeMetaSubrootInitOptions,
+	value: string
+): LeafNodeInitOptions => {
+	const instanceNode = buildMetaValueElement(subroot, DEPRECATED_ID_LOCAL_NAME, value);
+	const definition = buildDeprecatedIDDefinition(subroot, instanceNode);
+
+	return {
+		childNodeset: instanceNode.nodeset,
+		definition,
+		instanceNodes: [instanceNode],
+	};
+};
+
+const updateDeprecatedID = (
+	subroot: EditModeMetaSubrootInitOptions,
+	child: LeafNodeInitOptions,
+	value: string
+): LeafNodeInitOptions => {
+	const instanceNode = buildMetaValueElement(subroot, DEPRECATED_ID_LOCAL_NAME, value);
+
+	return {
+		childNodeset: child.childNodeset,
+		definition: child.definition,
+		instanceNodes: [instanceNode],
+	};
+};
+
+/**
+ * Should be: values.with(index, value)
+ *
+ * @todo update tsconfig.json `lib` throughout project!
+ */
+const replace = <T>(values: readonly T[], index: number, value: T): readonly T[] => {
+	const results = values.slice();
+
+	results.splice(index, 1, value);
+
+	return results;
+};
+
+const replaceOrConcat = <T>(values: readonly T[], index: number | null, value: T): readonly T[] => {
+	if (index == null) {
+		return values.concat(value);
+	}
+
+	return replace(values, index, value);
+};
+
+/**
+ * @todo Whenever we have bandwidth to start migrating away from DOM usage in
+ * {@link XFormDOM}, this is a good place to start for logic equivalent to the
+ * hacky normalization for `instanceID`.
+ */
+const populateDeprecatedID = (
+	subroot: EditModeMetaSubrootInitOptions
+): EditModeMetaSubrootInitOptions => {
+	const value = getInstanceIDValue(subroot);
+
+	if (value == null) {
+		return subroot;
+	}
+
+	const [index, currentDeprecatedID] = findMetaLeafChild(subroot, DEPRECATED_ID_LOCAL_NAME) ?? [
+		null,
+	];
+
+	let deprecatedID: LeafNodeInitOptions;
+
+	if (currentDeprecatedID == null) {
+		deprecatedID = buildDeprecatedID(subroot, value);
+	} else {
+		deprecatedID = updateDeprecatedID(subroot, currentDeprecatedID, value);
+	}
+
+	return {
+		model: subroot.model,
+		parent: subroot.parent,
+		children: replaceOrConcat(subroot.children, index, deprecatedID),
+	};
+};
+
+const normalizeMetaSubroot = (subroot: MetaSubrootInitOptions): MetaSubrootInitOptions => {
+	if (isEditModeMetaSubroot(subroot)) {
+		return populateDeprecatedID(subroot);
+	}
+
+	return subroot;
+};
+
+export const normalizeChildInitOptions = (options: ChildrenInitOptions): ChildrenInitOptions => {
+	if (isMetaSubroot(options)) {
+		return normalizeMetaSubroot(options);
+	}
+
+	return options;
+};