@getodk/xforms-engine 0.1.0

package/src/body/text/LabelDefinition.ts

@@ -0,0 +1,54 @@
+import { getLabelElement } from '../../lib/dom/query.ts';
+import type { XFormDefinition } from '../../XFormDefinition.ts';
+import type { AnyControlDefinition } from '../control/ControlDefinition.ts';
+import type { ItemDefinition } from '../control/select/ItemDefinition.ts';
+import type { ItemsetDefinition } from '../control/select/ItemsetDefinition.ts';
+import type { BaseGroupDefinition } from '../group/BaseGroupDefinition.ts';
+import type { TextElement, TextElementOwner } from './TextElementDefinition.ts';
+import { TextElementDefinition } from './TextElementDefinition.ts';
+
+export interface LabelElement extends TextElement {
+	readonly localName: 'label';
+}
+
+type StaticLabelContext = Exclude<TextElementOwner, ItemsetDefinition>;
+
+export class LabelDefinition extends TextElementDefinition<'label'> {
+	protected static staticDefinition(
+		form: XFormDefinition,
+		definition: StaticLabelContext
+	): LabelDefinition | null {
+		const labelElement = getLabelElement(definition.element);
+
+		if (labelElement == null) {
+			return null;
+		}
+
+		return new this(form, definition, labelElement);
+	}
+
+	static forControl(form: XFormDefinition, control: AnyControlDefinition): LabelDefinition | null {
+		return this.staticDefinition(form, control);
+	}
+
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	static forGroup(form: XFormDefinition, group: BaseGroupDefinition<any>): LabelDefinition | null {
+		return this.staticDefinition(form, group);
+	}
+
+	static forItem(form: XFormDefinition, item: ItemDefinition): LabelDefinition | null {
+		return this.staticDefinition(form, item);
+	}
+
+	static forItemset(form: XFormDefinition, itemset: ItemsetDefinition): LabelDefinition | null {
+		const labelElement = getLabelElement(itemset.element);
+
+		if (labelElement == null) {
+			return null;
+		}
+
+		return new this(form, itemset, labelElement);
+	}
+
+	readonly type = 'label';
+}

package/src/body/text/TextElementDefinition.ts

@@ -0,0 +1,97 @@
+import { isCommentNode, isElementNode, isTextNode } from '@getodk/common/lib/dom/predicates.ts';
+import type { XFormDefinition } from '../../XFormDefinition.ts';
+import { type AnyDependentExpression } from '../../expression/DependentExpression.ts';
+import type { AnyGroupElementDefinition } from '../BodyDefinition.ts';
+import { BodyElementDefinition } from '../BodyElementDefinition.ts';
+import type { InputDefinition } from '../control/InputDefinition.ts';
+import type { ItemDefinition } from '../control/select/ItemDefinition.ts';
+import type { ItemsetDefinition } from '../control/select/ItemsetDefinition.ts';
+import type { AnySelectDefinition } from '../control/select/SelectDefinition.ts';
+import { TextElementOutputPart } from './TextElementOutputPart.ts';
+import { TextElementReferencePart } from './TextElementReferencePart.ts';
+import { TextElementStaticPart } from './TextElementStaticPart.ts';
+
+export type TextElementType = 'hint' | 'label';
+
+export interface TextElement extends Element {
+	readonly localName: TextElementType;
+}
+
+export type TextElementOwner =
+	| AnyGroupElementDefinition
+	| AnySelectDefinition
+	| InputDefinition
+	| ItemDefinition
+	| ItemsetDefinition;
+
+export type TextElementChild = TextElementOutputPart | TextElementStaticPart;
+
+export abstract class TextElementDefinition<
+	Type extends TextElementType,
+> extends BodyElementDefinition<Type> {
+	readonly category = 'support';
+	abstract override readonly type: Type;
+
+	override readonly reference: string | null;
+	override readonly parentReference: string | null;
+
+	readonly referenceExpression: TextElementReferencePart | null;
+	readonly children: readonly TextElementChild[];
+
+	override get isTranslated(): boolean {
+		return this.owner.isTranslated;
+	}
+
+	override set isTranslated(value: true) {
+		this.owner.isTranslated = value;
+	}
+
+	protected constructor(
+		form: XFormDefinition,
+		readonly owner: TextElementOwner,
+		element: TextElement
+	) {
+		super(form, owner, element);
+
+		this.reference = owner.reference;
+		this.parentReference = owner.parentReference;
+		this.referenceExpression = TextElementReferencePart.from(this, element);
+
+		const children = Array.from(element.childNodes).flatMap((node) => {
+			if (isTextNode(node)) {
+				return new TextElementStaticPart(this, node);
+			}
+
+			if (isElementNode(node)) {
+				const output = TextElementOutputPart.from(this, node);
+
+				if (output != null) {
+					return output;
+				}
+			}
+
+			if (isCommentNode(node)) {
+				return [];
+			}
+
+			// eslint-disable-next-line no-console
+			console.error('Unexpected text element child', node);
+
+			throw new Error(`Unexpected <${element.nodeName}> child element`);
+		});
+
+		this.children = children;
+	}
+
+	override registerDependentExpression(expression: AnyDependentExpression): void {
+		this.owner.registerDependentExpression(expression);
+	}
+
+	override toJSON(): object {
+		const { form, owner, parent, ...rest } = this;
+
+		return rest;
+	}
+}
+
+export type AnyTextElementDefinition = TextElementDefinition<TextElementType>;

package/src/body/text/TextElementOutputPart.ts

@@ -0,0 +1,27 @@
+import type { AnyTextElementDefinition } from './TextElementDefinition.ts';
+import { TextElementPart } from './TextElementPart.ts';
+
+interface OutputElement extends Element {
+	readonly localName: 'output';
+
+	getAttribute(name: 'value'): string;
+	getAttribute(name: string): string | null;
+}
+
+const isOutputElement = (element: Element): element is OutputElement => {
+	return element.localName === 'output' && element.hasAttribute('value');
+};
+
+export class TextElementOutputPart extends TextElementPart<'output'> {
+	static from(context: AnyTextElementDefinition, element: Element): TextElementOutputPart | null {
+		if (isOutputElement(element)) {
+			return new this(context, element);
+		}
+
+		return null;
+	}
+
+	protected constructor(context: AnyTextElementDefinition, element: OutputElement) {
+		super('output', context, element.getAttribute('value'));
+	}
+}

package/src/body/text/TextElementPart.ts

@@ -0,0 +1,31 @@
+import { DependentExpression } from '../../expression/DependentExpression.ts';
+import type { AnyTextElementDefinition } from './TextElementDefinition.ts';
+import type { TextElementOutputPart } from './TextElementOutputPart.ts';
+import type { TextElementReferencePart } from './TextElementReferencePart.ts';
+import type { TextElementStaticPart } from './TextElementStaticPart.ts';
+
+export type TextElementPartType = 'output' | 'reference' | 'static';
+
+export abstract class TextElementPart<
+	Type extends TextElementPartType,
+> extends DependentExpression<'string'> {
+	readonly stringValue?: string;
+
+	constructor(
+		readonly type: Type,
+		context: AnyTextElementDefinition,
+		expression: string
+	) {
+		super(context, 'string', expression, {
+			semanticDependencies: {
+				translations: type !== 'static',
+			},
+			ignoreContextReference: true,
+		});
+	}
+}
+
+export type AnyTextElementPart =
+	| TextElementOutputPart
+	| TextElementReferencePart
+	| TextElementStaticPart;

package/src/body/text/TextElementReferencePart.ts

@@ -0,0 +1,21 @@
+import type { AnyTextElementDefinition, TextElement } from './TextElementDefinition.ts';
+import { TextElementPart } from './TextElementPart.ts';
+
+export class TextElementReferencePart extends TextElementPart<'reference'> {
+	static from(
+		context: AnyTextElementDefinition,
+		element: TextElement
+	): TextElementReferencePart | null {
+		const expression = element.getAttribute('ref');
+
+		if (expression == null) {
+			return null;
+		}
+
+		return new this(context, expression);
+	}
+
+	protected constructor(context: AnyTextElementDefinition, expression: string) {
+		super('reference', context, expression);
+	}
+}

package/src/body/text/TextElementStaticPart.ts

@@ -0,0 +1,26 @@
+import type { AnyTextElementDefinition } from './TextElementDefinition.ts';
+import { TextElementPart } from './TextElementPart.ts';
+
+const toStaticXPathExpression = (staticTextValue: string): string => {
+	const quote = staticTextValue.includes('"') ? "'" : '"';
+
+	if (staticTextValue.includes(quote)) {
+		// throw new Error('todo concat()');
+		return 'todo(concat())';
+	}
+
+	return `${quote}${staticTextValue}${quote}`;
+};
+
+export class TextElementStaticPart extends TextElementPart<'static'> {
+	override readonly stringValue: string;
+
+	constructor(context: AnyTextElementDefinition, node: Text) {
+		const stringValue = node.data;
+		const expression = toStaticXPathExpression(stringValue);
+
+		super('static', context, expression);
+
+		this.stringValue = stringValue;
+	}
+}

package/src/client/BaseNode.ts

@@ -0,0 +1,180 @@
+import type { AnyNodeDefinition } from '../model/NodeDefinition.ts';
+import type { InstanceNodeType } from './node-types.js';
+import type { OpaqueReactiveObjectFactory } from './OpaqueReactiveObjectFactory.ts';
+import type { TextRange } from './TextRange.ts';
+
+export interface BaseNodeState {
+	/**
+	 * Location path reference to the node's primary instance state. This property
+	 * may change if a node's position changes, e.g. when a repeat instance is
+	 * removed. Its potential reactivity allows nodes to re-run computations which
+	 * depend on the node's position itself, or when any other relative reference
+	 * might target different nodes as a result of the positional change.
+	 *
+	 * @example
+	 * /data/repeat[1]/foo
+	 * /data/repeat[2]/foo
+	 */
+	get reference(): string;
+
+	/**
+	 * Note: a node's `readonly` state may become `true` by inheriting that state
+	 * from one of its ancestors. Computing this inheritance is handled by the
+	 * engine, but it may be of interest to clients.
+	 *
+	 * In the future, a more granular type might convey this detail more
+	 * explicitly (at the expense of a more complex type). For now, a client can
+	 * infer that inheritance by visiting the
+	 * {@link BaseNode.parent | parent node}.
+	 */
+	get readonly(): boolean;
+
+	/**
+	 * Note: a node's `relevant` state may become `false` by inheriting that state
+	 * from one of its ancestors. Computing this inheritance is handled by the
+	 * engine, but it may be of interest to clients.
+	 *
+	 * In the future, a more granular type might convey this detail more
+	 * explicitly (at the expense of a more complex type). For now, a client can
+	 * infer that inheritance by visiting the
+	 * {@link BaseNode.parent | parent node}.
+	 */
+	get relevant(): boolean;
+
+	// Note: according to spec, `required` is NOT inherited from ancestor nodes.
+	// What this means for a `required` state on subtree nodes is an open
+	// question. It was also raised on the first engine-internals iteration, and I
+	// could have sworn it was discussed in that PR, but finding any record of
+	// this discussion has proven elusive.
+	get required(): boolean;
+
+	/**
+	 * Interfaces for nodes which cannot provide a label should override this to
+	 * specify that the property will always be `null`.
+	 */
+	get label(): TextRange<'label'> | null;
+
+	/**
+	 * Interfaces for nodes which cannot provide a hint should override this to
+	 * specify that the property will always be `null`.
+	 */
+	get hint(): TextRange<'hint'> | null;
+
+	/**
+	 * Each node's children (if it is a parent node) will be accessed on that
+	 * node's state. While some node types will technically have static children,
+	 * other nodes' children will be stateful (i.e. repeats). For a client, both
+	 * cases are accessed the same way for consistency.
+	 *
+	 * Certain kinds of nodes are considered parent nodes: they may have child
+	 * nodes. In some cases (presently, repeat ranges), children may be added or
+	 * removed while a user is filling a form. As such, those children must be
+	 * accessed as part of the node's
+	 * {@link BaseNode.currentState | current state}. (In contrast, child nodes
+	 * are never moved between different parents, so their
+	 * {@link BaseNode.parent | parent} is static rather than part of their
+	 * current state).
+	 *
+	 * A node is either:
+	 *
+	 * - Always a parent, in which case its `children` state should always produce
+	 *   an array. When the parent node's children can be added or removed, an
+	 *   empty array should be used to represent the absence of any children in
+	 *   its current state.
+	 * - Never a parent, in which case its `children` state should always produce
+	 *   `null`. Such a node will instead have a {@link value}.
+	 */
+	get children(): readonly BaseNode[] | null;
+
+	/**
+	 * Certain kinds of nodes restrict their {@link value} to a specific set of
+	 * valid values. Where they do, they will provide a collection (typically an
+	 * array) of those values. This collection may be updated depending on other
+	 * aspects of form state, which is why it is treated as a part of the node's
+	 * state.
+	 *
+	 * Nodes which do not have this restriction (including nodes which cannot have
+	 * a value at all) will always produce `valueOptions: null`.
+	 */
+	get valueOptions(): unknown;
+
+	/**
+	 * Certain kinds of nodes store a value state. Where they do, they will
+	 * specify the type of the value directly.
+	 *
+	 * Parent nodes, i.e. nodes which can contain {@link children}, do not store a
+	 * value state. For those nodes, their value state should always be `null`.
+	 */
+	get value(): unknown;
+}
+
+type FormNodeID = string;
+
+/**
+ * Base interface for common/shared aspects of any node type.
+ */
+export interface BaseNode {
+	/**
+	 * Specifies the node's general type. This can be useful for narrowing types,
+	 * e.g. those of children.
+	 */
+	readonly nodeType: InstanceNodeType;
+
+	/**
+	 * Each node has a unique identifier. This identifier is stable throughout
+	 * the lifetime of an active session filling a form.
+	 */
+	readonly nodeId: FormNodeID;
+
+	/**
+	 * Each node has a definition which specifies aspects of the node defined in
+	 * the form. These aspects include (but are not limited to) the node's data
+	 * type, its body presentation constraints (if any), its bound nodeset, and
+	 * so on...
+	 *
+	 * @todo Interfaces for specific (non-base) node types should override this
+	 * to specify the actual (concrete or union) type of their `definition`.
+	 */
+	readonly definition: AnyNodeDefinition;
+
+	/**
+	 * Each node links back to the node representing the root of the form.
+	 *
+	 * @todo Interfaces for all concrete node types should override this to
+	 * specify the actual root node type.
+	 */
+	readonly root: BaseNode;
+
+	/**
+	 * Each node links back to its parent, if any. All nodes have a parent except
+	 * the form's {@link root}.
+	 */
+	// TODO: the `children` state property discusses the fact that a child node
+	// cannot be reassigned to another parent. As such, it is currently treated as
+	// static. This fails to address the removal of nodes, i.e. when removing
+	// repeat instances. This suggests that perhaps `parent` should also be part
+	// of the node's state. However that would be insufficient to communicate the
+	// same information about a removed node's descendants. Some considerations:
+	//
+	// 1. If `parent` becomes part of state, how do we communicate that removal is
+	//    the only possible state change (as in, a child node will never be
+	//    reassigned to another parent)?
+	// 2. If `parent` does become nullable state, how best to convey the same
+	//    information for removed descendants. Some ideas:
+	//
+	//    - Apply null-as-removed recursively. This wouldn't technically be true
+	//      for the engine's current use of a DOM backing store (but that's an
+	//      implementation detail clients don't/shouldn't care about).
+	//
+	//    - Borrow the browser DOM's notion of node "connected"-ness. When a node
+	//      is removed, its `isConnected` property is `false`. The same is true
+	//      for any of its descendants, even though they retain their own direct
+	//      parent reference.
+	readonly parent: BaseNode | null;
+
+	/**
+	 * Each node provides a discrete object representing the stateful aspects of
+	 * that node which will change over time. When a client provides a {@link OpaqueReactiveObjectFactory}
+	 */
+	readonly currentState: BaseNodeState;
+}

package/src/client/EngineConfig.ts

@@ -0,0 +1,83 @@
+import type { OpaqueReactiveObjectFactory } from './OpaqueReactiveObjectFactory.ts';
+
+/**
+ * @todo this is currently a strict subset of the web standard `Response`. Is it
+ * sufficient? Ways it might not be:
+ *
+ * - No way to convey metadata about the resource
+ * - Ambiguous if a client supplies an alternative implementation which doesn't
+ *   exhaust the body on access
+ */
+export interface FetchResourceResponse {
+	readonly ok?: boolean;
+	readonly body?: ReadableStream<Uint8Array> | null;
+	readonly bodyUsed?: boolean;
+
+	readonly blob: () => Promise<Blob>;
+	readonly text: () => Promise<string>;
+}
+
+/**
+ * @todo this is a strict subset of the web standard `fetch` interface. It
+ * implicitly assumes that the engine itself will only ever issue `GET`-like
+ * requests. It also provides no further request-like semantics to the engine.
+ * This is presumed sufficient for now, but notably doesn't expose any notion of
+ * content negotiation (e.g. the ability to supply `Accept` headers).
+ *
+ * This also completely ignores any notion of mapping
+ * {@link https://getodk.github.io/xforms-spec/#uris | `jr:` URLs} to their
+ * actual resources (likely, but not necessarily, accessed at a corresponding
+ * HTTP URL).
+ */
+export type FetchResource = (resource: URL) => Promise<FetchResourceResponse>;
+
+/**
+ * Options provided by a client to specify certain aspects of engine runtime
+ * behavior. These options will generally be intended to facilitate cooperation
+ * where there is mixed responsibility between a client and the engine, or where
+ * the engine may provide sensible defaults which a client could be expected to
+ * override or augment.
+ */
+export interface EngineConfig {
+	/**
+	 * A client may specify a generic function for constructing stateful objects.
+	 * The only hard requirement of this function is that it accepts an **object**
+	 * and returns an object of the same shape. The engine will use this function
+	 * to initialize client-facing state, and will mutate properties of the object
+	 * when their corresponding state is changed.
+	 *
+	 * A client may use this function to provide its own implementation of
+	 * reactivity with semantics like those described above. The mechanism of
+	 * reactivity, if any, is at the discretion of the client. It is expected
+	 * that clients providing this function will use a reactive subscribe-on-read
+	 * mechanism to handle state updates conveyed by the engine.
+	 */
+	readonly stateFactory?: OpaqueReactiveObjectFactory;
+
+	/**
+	 * A client may specify a generic function for retrieving resources referenced
+	 * by a form, such as:
+	 *
+	 * - Form definitions themselves (if not provided directly to the engine by
+	 *   the client)
+	 * - External secondary instances
+	 * - Media (images, audio, video, etc.)
+	 *
+	 * The function is expected to be a subset of the
+	 * {@link https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API | Fetch API},
+	 * performing `GET` requests for:
+	 *
+	 * - Text resources (e.g. XML, CSV, JSON/GeoJSON)
+	 * - Binary resources (e.g. media)
+	 * - Optionally streamed binary data of either (e.g. for optimized
+	 *   presentation of audio/video)
+	 *
+	 * If provided by a client, this function will be used by the engine to
+	 * retrieve any such resource, as required for engine functionality. If
+	 * absent, the engine will use the native `fetch` function (if available, a
+	 * polyfill otherwise). Clients may use this function to provide resources
+	 * from sources other than the network, (or even in a test client to provide
+	 * e.g. resources from test fixtures).
+	 */
+	readonly fetchResource?: FetchResource;
+}

package/src/client/FormLanguage.ts

@@ -0,0 +1,77 @@
+interface BaseFormLanguage {
+	/**
+	 * @see {@link ActiveLanguage} for details.
+	 */
+	readonly isSyntheticDefault?: true;
+
+	/**
+	 * As derived directly from the form's
+	 * {@link https://getodk.github.io/xforms-spec/#languages | `itext` translations}.
+	 */
+	readonly language: string;
+
+	/**
+	 * Where possible, a form's languages may detect the standardized locale
+	 * corresponding to the language as specified in the form.
+	 */
+	// NOTE: this is proposed, hypothetical future functionality. Enketo has
+	// similar functionality, but we'll want to seriously consider how best to
+	// accomplish this if/as it becomes a priority.
+	readonly locale?: Intl.Locale;
+}
+
+/**
+ * @see {@link ActiveLanguage} for details.
+ */
+export interface SyntheticDefaultLanguage extends BaseFormLanguage {
+	readonly isSyntheticDefault: true;
+	readonly language: '';
+}
+
+/**
+ * A language available for a given form, as defined by that form's {@link https://getodk.github.io/xforms-spec/#languages | `itext` translations}.
+ *
+ * @see {@link ActiveLanguage} for additional details.
+ */
+export interface FormLanguage extends BaseFormLanguage {
+	readonly isSyntheticDefault?: never;
+}
+
+/**
+ * A form with translations will always have one or more {@link FormLanguage}s,
+ * with the default chosen as described in the ODK XForms specification.
+ *
+ * A form that specifies no translations will always have a single
+ * {@link SyntheticDefaultLanguage}.
+ *
+ * No form will ever combine both types of language.
+ *
+ * This distinction is intended to avoid confusion about the **potential** state
+ * of a form's active language. A naive type to express the possibility, without
+ * a synthetic default, would be something like `FormLanguage | null`, which
+ * would seem to suggest to a client that a form may **only sometimes** have an
+ * active language—for instance, that there might be a way for a client to turn
+ * translation off and on.
+ *
+ * By ensuring there is always _some active language value_, and by expressing
+ * the {@link FormLanguages} type to correspond to each of the possibilities
+ * discussed above, it's hoped that the set of potential translation states a
+ * client might encounter/establish are more clear.
+ */
+// prettier-ignore
+export type ActiveLanguage =
+	| FormLanguage
+	| SyntheticDefaultLanguage;
+
+/**
+ * A form may either have:
+ *
+ * - one or more available {@link FormLanguage}s, as defined by the form
+ * - exactly one {@link SyntheticDefaultLanguage}
+ *
+ * @see {@link ActiveLanguage} for additional details.
+ */
+// prettier-ignore
+export type FormLanguages =
+	| readonly [FormLanguage, ...FormLanguage[]]
+	| readonly [SyntheticDefaultLanguage];

package/src/client/GroupNode.ts

@@ -0,0 +1,33 @@
+import type { NonRepeatGroupElementDefinition } from '../body/BodyDefinition.ts';
+import type { SubtreeDefinition } from '../model/SubtreeDefinition.ts';
+import type { BaseNode, BaseNodeState } from './BaseNode.ts';
+import type { RootNode } from './RootNode.ts';
+import type { GeneralChildNode, GeneralParentNode } from './hierarchy.ts';
+
+export interface GroupNodeState extends BaseNodeState {
+	get hint(): null;
+	get children(): readonly GeneralChildNode[];
+	get valueOptions(): null;
+	get value(): null;
+}
+
+// TODO: as with `SubtreeNode`'s `SubtreeDefinition`, there is a naming
+// inconsistency emerging here.
+export interface GroupDefinition extends SubtreeDefinition {
+	readonly bodyElement: NonRepeatGroupElementDefinition;
+}
+
+/**
+ * A node corresponding to an XForms `<group>`.
+ */
+// TODO: test (fix?) case where a `<group>` is implicitly connected to a
+// subtree, but doesn't reference it directly. See
+// https://github.com/getodk/web-forms/blob/6cfff8b4c5a2cf6a23a71ef6d4308343bccd2436/packages/odk-web-forms/src/lib/xform/model/ModelDefinition.test.ts#L480-L540
+// for context.
+export interface GroupNode extends BaseNode {
+	readonly nodeType: 'group';
+	readonly definition: GroupDefinition;
+	readonly root: RootNode;
+	readonly parent: GeneralParentNode;
+	readonly currentState: GroupNodeState;
+}