@getodk/xforms-engine 0.1.1 → 0.3.0

package/src/instance/RepeatRange.ts

@@ -1,214 +0,0 @@
-import { insertAtIndex } from '@getodk/common/lib/array/insert.ts';
-import type { Accessor } from 'solid-js';
-import type { RepeatRangeNode } from '../client/RepeatRangeNode.ts';
-import type { ChildrenState } from '../lib/reactivity/createChildrenState.ts';
-import { createChildrenState } from '../lib/reactivity/createChildrenState.ts';
-import type { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
-import { materializeCurrentStateChildren } from '../lib/reactivity/materializeCurrentStateChildren.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 { createNodeLabel } from '../lib/reactivity/text/createNodeLabel.ts';
-import type { RepeatSequenceDefinition } from '../model/RepeatSequenceDefinition.ts';
-import type { RepeatDefinition } from './RepeatInstance.ts';
-import { RepeatInstance } from './RepeatInstance.ts';
-import type { Root } from './Root.ts';
-import type { DescendantNodeSharedStateSpec } from './abstract/DescendantNode.ts';
-import { DescendantNode } from './abstract/DescendantNode.ts';
-import type { GeneralParentNode } from './hierarchy.ts';
-import type { NodeID } from './identity.ts';
-import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
-import type { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
-import type { TextRange } from './text/TextRange.ts';
-
-interface RepeatRangeStateSpec extends DescendantNodeSharedStateSpec {
-	readonly hint: null;
-	readonly label: Accessor<TextRange<'label'> | null>;
-	readonly children: Accessor<readonly NodeID[]>;
-	readonly valueOptions: null;
-	readonly value: null;
-}
-
-export class RepeatRange
-	extends DescendantNode<RepeatSequenceDefinition, RepeatRangeStateSpec, RepeatInstance>
-	implements RepeatRangeNode, EvaluationContext, SubscribableDependency
-{
-	/**
-	 * A repeat range doesn't have a corresponding primary instance element of its
-	 * own, and its instances are appended to the range's parent element. During
-	 * creation of the initial primary instance state and DOM trees, we _could_
-	 * reliably append all of the range's instances in order as the definition
-	 * tree is recursed. But that would fail to handle some instance addition
-	 * cases afterwards.
-	 *
-	 * Most notably, we need to know where in the primary instance tree to append
-	 * instances created for a range which is currently empty. As a lucky
-	 * coincidence, this need coincides with the ability to add instances at any
-	 * arbitrary index within the range. In each case, we can reference a primary
-	 * instance DOM node which will become the new instance's preceding sibling.
-	 * Where the range is empty, we use this {@link Comment} node (itself created
-	 * and appended during range initialization) in lieu of a nonexistent
-	 * preceding instance's {@link contextNode}.
-	 *
-	 * @todo We likely want to remove these during submission serialization.
-	 * @todo Can we use a
-	 * {@link https://developer.mozilla.org/en-US/docs/Web/API/Range | DOM Range}
-	 * instead?
-	 */
-	private readonly anchorNode: Comment;
-
-	private readonly childrenState: ChildrenState<RepeatInstance>;
-
-	// InstanceNode
-	protected readonly state: SharedNodeState<RepeatRangeStateSpec>;
-	protected override engineState: EngineState<RepeatRangeStateSpec>;
-
-	// RepeatRangeNode
-	readonly nodeType = 'repeat-range';
-
-	readonly currentState: MaterializedChildren<CurrentState<RepeatRangeStateSpec>, RepeatInstance>;
-
-	constructor(parent: GeneralParentNode, definition: RepeatSequenceDefinition) {
-		super(parent, definition);
-
-		const childrenState = createChildrenState<RepeatRange, RepeatInstance>(this);
-
-		this.childrenState = childrenState;
-
-		const state = createSharedNodeState(
-			this.scope,
-			{
-				...this.buildSharedStateSpec(parent, definition),
-
-				label: createNodeLabel(this, definition),
-				hint: null,
-				children: childrenState.childIds,
-				valueOptions: null,
-				value: null,
-			},
-			{
-				clientStateFactory: this.engineConfig.stateFactory,
-			}
-		);
-
-		this.anchorNode = this.contextNode.ownerDocument.createComment(
-			`Begin repeat range: ${definition.nodeset}`
-		);
-		this.contextNode.append(this.anchorNode);
-
-		this.state = state;
-		this.engineState = state.engineState;
-		this.currentState = materializeCurrentStateChildren(state.currentState, childrenState);
-
-		definition.instances.forEach((instanceDefinition, index) => {
-			const afterIndex = index - 1;
-
-			this.addInstances(afterIndex, 1, instanceDefinition);
-		});
-	}
-
-	private getLastIndex(): number {
-		return this.engineState.children.length - 1;
-	}
-
-	protected override initializeContextNode(parentContextNode: Element): Element {
-		return parentContextNode;
-	}
-
-	protected computeReference(parent: GeneralParentNode): string {
-		return this.computeChildStepReference(parent);
-	}
-
-	getInstanceIndex(instance: RepeatInstance): number {
-		return this.engineState.children.indexOf(instance.nodeId);
-	}
-
-	addInstances(
-		afterIndex = this.getLastIndex(),
-		count = 1,
-		definition: RepeatDefinition = this.definition.template
-	): Root {
-		return this.scope.runTask(() => {
-			let precedingInstance: RepeatInstance | null;
-
-			if (afterIndex === -1) {
-				precedingInstance = null;
-			} else {
-				const instance = this.childrenState.getChildren()[afterIndex];
-
-				if (instance == null) {
-					throw new Error(`No repeat instance at index ${afterIndex}`);
-				}
-
-				precedingInstance = instance;
-			}
-
-			const precedingPrimaryInstanceNode = precedingInstance?.contextNode ?? this.anchorNode;
-
-			const newInstance = new RepeatInstance(this, definition, {
-				precedingPrimaryInstanceNode,
-				precedingInstance,
-			});
-			const initialIndex = afterIndex + 1;
-
-			this.childrenState.setChildren((currentInstances) => {
-				return insertAtIndex(currentInstances, initialIndex, newInstance);
-			});
-
-			if (count > 1) {
-				return this.addInstances(initialIndex, count - 1);
-			}
-
-			return this.root;
-		});
-	}
-
-	/**
-	 * Removes the {@link RepeatInstance}s corresponding to the specified range of
-	 * indexes, and then removes those repeat instances from the repeat range's
-	 * own children state in that order:
-	 *
-	 * 1. Identify the set of {@link RepeatInstance}s to be removed.
-	 *
-	 * 2. For each {@link RepeatInstance} pending removal, perform that node's
-	 *    removal logic. @see {@link RepeatInstance.remove} for more detail.
-	 *
-	 * 3. Finalize update to the repeat range's own {@link childrenState},
-	 *    omitting those {@link RepeatInstance}s which were removed.
-	 *
-	 * This ordering ensures a consistent representation of state is established
-	 * prior to any downstream reactive updates, and ensures that removed nodes'
-	 * reactivity is cleaned up.
-	 */
-	removeInstances(startIndex: number, count = 1): Root {
-		return this.scope.runTask(() => {
-			this.childrenState.setChildren((currentInstances) => {
-				const updatedInstances = currentInstances.slice();
-				const removedInstances = updatedInstances.splice(startIndex, count);
-
-				removedInstances.forEach((instance) => {
-					instance.remove();
-				});
-
-				return updatedInstances;
-			});
-
-			return this.root;
-		});
-	}
-
-	override subscribe(): void {
-		super.subscribe();
-
-		// Subscribing to children can support reactive expressions dependent on the
-		// repeat range itself (e.g. `count()`).
-		this.childrenState.getChildren().forEach((child) => {
-			child.subscribe();
-		});
-	}
-
-	getChildren(): readonly RepeatInstance[] {
-		return this.childrenState.getChildren();
-	}
-}

package/src/lib/xpath/analysis.ts

@@ -1,241 +0,0 @@
-import { UnreachableError } from '@getodk/common/lib/error/UnreachableError';
-import { expressionParser } from '@getodk/xpath/expressionParser.js';
-import type {
-	AbsoluteLocationPathNode,
-	AnyBinaryExprNode,
-	AnySyntaxNode,
-	FilterPathExprNode,
-	LocalPartNode,
-	PrefixedNameNode,
-	RelativeLocationPathNode,
-	UnprefixedNameNode,
-} from '@getodk/xpath/static/grammar/SyntaxNode.js';
-import type { AnyBinaryExprType } from '@getodk/xpath/static/grammar/type-names.js';
-
-export type SingleChildNode = Extract<
-	AnySyntaxNode,
-	{ readonly children: readonly [AnySyntaxNode] }
->;
-
-const isSingleNodeChild = (node: AnySyntaxNode): node is SingleChildNode => {
-	return node.childCount === 1;
-};
-
-const binaryExprNodeTypes = new Set<AnyBinaryExprType>([
-	'addition_expr',
-	'and_expr',
-	'division_expr',
-	'eq_expr',
-	'gt_expr',
-	'gte_expr',
-	'lt_expr',
-	'lte_expr',
-	'modulo_expr',
-	'multiplication_expr',
-	'ne_expr',
-	'or_expr',
-	'subtraction_expr',
-	'union_expr',
-]);
-
-const isBinaryExprNode = (node: AnySyntaxNode): node is AnyBinaryExprNode => {
-	return binaryExprNodeTypes.has(node.type as AnyBinaryExprType);
-};
-
-const matchesLocalName = (
-	localName: string,
-	nameNode: PrefixedNameNode | UnprefixedNameNode
-): boolean => {
-	const localPartNode: LocalPartNode | UnprefixedNameNode =
-		nameNode.type === 'prefixed_name' ? nameNode.children[1] : nameNode;
-
-	return localPartNode.text === localName;
-};
-
-const isFunctionCalled = (localName: string, node: AnySyntaxNode): boolean => {
-	if (!node.text.includes(localName)) {
-		return false;
-	}
-
-	if (isSingleNodeChild(node)) {
-		const [child] = node.children;
-
-		return isFunctionCalled(localName, child);
-	}
-
-	if (isBinaryExprNode(node)) {
-		const [lhs, rhs] = node.children;
-
-		return isFunctionCalled(localName, lhs) || isFunctionCalled(localName, rhs);
-	}
-
-	switch (node.type) {
-		// Terminal nodes
-		case 'number':
-		case 'string_literal':
-		case 'variable_reference':
-
-		// Path sub-nodes which could not have a function call child
-		//
-		// This only errors because this set of cases is commented:
-		// eslint-disable-next-line no-fallthrough
-		case '//':
-		case 'absolute_root_location_path':
-		case 'axis_name':
-		case 'node_type_test':
-		case 'parent':
-		case 'self':
-
-		// Name nodes are also not function call parents
-		//
-		// This only errors because this set of cases is commented:
-		// eslint-disable-next-line no-fallthrough
-		case 'local_part':
-		case 'prefixed_name':
-		case 'prefix':
-		case 'unprefixed_name':
-		case 'unprefixed_wildcard_name_test':
-			return false;
-
-		// Path sub-nodes which could have a function call child
-		case 'abbreviated_absolute_location_path':
-		case 'abbreviated_step':
-		case 'absolute_location_path':
-		case 'axis_test':
-		case 'filter_path_expr':
-		case 'relative_location_path':
-		case 'step':
-			return node.children.some((childNode) => isFunctionCalled(localName, childNode));
-
-		case 'function_call': {
-			const [functionNameNode] = node.children;
-			const [nameNode] = functionNameNode.children;
-
-			return matchesLocalName(localName, nameNode);
-		}
-
-		default:
-			throw new UnreachableError(node);
-	}
-};
-
-export const isItextFunctionCalled = (expression: string): boolean => {
-	const { rootNode } = expressionParser.parse(expression);
-
-	return isFunctionCalled('itext', rootNode);
-};
-
-type LocationPathSubExpressionNode =
-	| AbsoluteLocationPathNode
-	| FilterPathExprNode
-	| RelativeLocationPathNode;
-
-const isAnyLocationPathExprNode = (node: AnySyntaxNode): node is LocationPathSubExpressionNode => {
-	const { type } = node;
-
-	if (type === 'absolute_location_path' || type === 'relative_location_path') {
-		return true;
-	}
-
-	return false;
-};
-
-// TODO: this does not currently even attempt to find sub-expressions nested
-// within sub-expressions.
-const findLocationPathExprNodes = (
-	node: AnySyntaxNode
-): readonly LocationPathSubExpressionNode[] => {
-	const results: LocationPathSubExpressionNode[] = [];
-
-	if (isAnyLocationPathExprNode(node)) {
-		results.push(node);
-	}
-
-	results.push(
-		...node.children.flatMap((childNode) => {
-			return findLocationPathExprNodes(childNode);
-		})
-	);
-
-	return results;
-};
-
-// TODO: this is a very small subset of resolution that needs to be supported,
-// and it's a hamfisted hack. **This is temporary** to unblock progress on
-// computations, but a longer term solution will need to address:
-//
-// - non-abbreviation axes (parent, child, self) according to XForms spec
-// - non-leading axes
-// - context expressions which are more complex than a series of explicit
-//   element name test steps (this may be fine for binds!)
-const resolveRelativeSubExpression = (contextReference: string | null, expression: string) => {
-	if (contextReference == null) {
-		return expression;
-	}
-
-	const [, axisAbbreviation, relativeExpression = ''] = expression.match(/^(\.{1,2})(\/.*$)?/) ?? [
-		null,
-		'',
-		expression,
-	];
-
-	switch (axisAbbreviation) {
-		case '':
-			return expression;
-
-		case '.':
-			return `${contextReference}${relativeExpression}`;
-
-		case '..':
-			return `${contextReference.replace(/\/[^/]+$/, '')}${relativeExpression}`;
-	}
-
-	throw new Error(`Unexpected relative expression: ${expression}`);
-};
-
-interface GetNodesetDependenciesOptions {
-	readonly contextReference?: string | null;
-
-	/**
-	 * @default false
-	 */
-	readonly ignoreContextReference?: boolean;
-
-	/**
-	 * Ignores location path sub-expressions whose full text is `null`. While this
-	 * is technically a valid relative name test step, it seems that real forms in
-	 * the wild use it as if XPath had an actual `null` token/value.
-	 *
-	 * @default true
-	 */
-	readonly ignoreNullExpressions?: boolean;
-}
-
-export const getNodesetDependencies = (
-	expression: string,
-	options: GetNodesetDependenciesOptions = {}
-): Set<string> => {
-	const { rootNode } = expressionParser.parse(expression);
-	const subExpressionNodes = findLocationPathExprNodes(rootNode);
-	const {
-		contextReference = null,
-		ignoreContextReference = false,
-		ignoreNullExpressions = true,
-	} = options;
-
-	const subExpressions = subExpressionNodes
-		.map((syntaxNode) => resolveRelativeSubExpression(contextReference, syntaxNode.text))
-		.filter((subExpression) => {
-			if (ignoreContextReference && subExpression === contextReference) {
-				return false;
-			}
-
-			if (ignoreNullExpressions && subExpression === 'null') {
-				return false;
-			}
-
-			return true;
-		});
-
-	return new Set(subExpressions);
-};

package/src/model/RepeatSequenceDefinition.ts

@@ -1,53 +0,0 @@
-import { RepeatGroupDefinition } from '../body/group/RepeatGroupDefinition.ts';
-import type { BindDefinition } from './BindDefinition.ts';
-import { DescendentNodeDefinition } from './DescendentNodeDefinition.ts';
-import type { NodeDefinition, ParentNodeDefinition } from './NodeDefinition.ts';
-import { RepeatInstanceDefinition } from './RepeatInstanceDefinition.ts';
-import { RepeatTemplateDefinition } from './RepeatTemplateDefinition.ts';
-
-export class RepeatSequenceDefinition
-	extends DescendentNodeDefinition<'repeat-sequence', RepeatGroupDefinition>
-	implements NodeDefinition<'repeat-sequence'>
-{
-	// TODO: if an implicit template is derived from an instance in a form
-	// definition, should its default values (if any) be cleared? Probably!
-	static createTemplateElement(instanceElement: Element): Element {
-		return instanceElement.cloneNode(true) as Element;
-	}
-
-	static createInstanceElement(templateElement: Element): Element {
-		return templateElement.cloneNode(true) as Element;
-	}
-
-	readonly type = 'repeat-sequence';
-
-	readonly template: RepeatTemplateDefinition;
-	readonly children = null;
-	readonly instances: RepeatInstanceDefinition[];
-
-	readonly node = null;
-	readonly nodeName: string;
-	readonly defaultValue = null;
-
-	constructor(
-		parent: ParentNodeDefinition,
-		bind: BindDefinition,
-		bodyElement: RepeatGroupDefinition,
-		modelNodes: readonly [Element, ...Element[]]
-	) {
-		super(parent, bind, bodyElement);
-		const { template, instanceNodes } = RepeatTemplateDefinition.parseModelNodes(this, modelNodes);
-
-		this.template = template;
-		this.nodeName = template.nodeName;
-		this.instances = instanceNodes.map((element) => {
-			return new RepeatInstanceDefinition(this, element);
-		});
-	}
-
-	toJSON() {
-		const { bind, bodyElement: groupDefinition, parent, root, ...rest } = this;
-
-		return rest;
-	}
-}