@getodk/xforms-engine 0.2.0 → 0.3.0

package/src/client/TextRange.ts

@@ -1,7 +1,70 @@
 import type { ActiveLanguage } from './FormLanguage.ts';
 import type { RootNodeState } from './RootNode.ts';
 
-export type TextChunkSource = 'itext' | 'output' | 'static';
+/**
+ * **COMMENTARY**
+ *
+ * The spec makes naming and mapping these cases a bit more complex than would
+ * be ideal. The intent is to clearly identify distinct text definitions (and
+ * sub-structural parts) from a source form, in a way that semantically lines up
+ * with the ways they will need to be handled at runtime and conveyed to
+ * clients. This is the mapping:
+ *
+ * - 'output': All output values, i.e.:
+ *   - `output/@value`
+ *
+ * - 'translation':
+ *
+ *   - Valid XPath translation expressions, in a context accepting mixed
+ *     translation/static syntax, i.e.:
+ *
+ *     - `h:head//bind/@jr:constraintMsg[is-translation-expr()]`
+ *     - `h:head//bind/@jr:requiredMsg[is-translation-expr()]`
+ *
+ *       Here, `is-translation-expr()` is a fictional shorthand for checking
+ *       that the attribute's value is a valid `jr:itext(...)` FunctionCall
+ *       expression. Note that, per spec, these attributes **do not accept
+ *       arbitrary XPath expressions**! The non-translation case is  treated as
+ *       static text, not parsed for e.g. an XPath [string] Literal expression.
+ *       This is why we have introduced this 'translation' case, distinct from
+ *       'reference', which previously handled translated labels and hints.
+ *
+ *   - Valid XPath translation expressions, in a context accepting arbitrary
+ *     XPath expressions, i.e.:
+ *
+ *     - `h:body//label/@ref[is-translation-expr()]`
+ *
+ * - 'static':
+ *   - `h:head//bind/@jr:constraintMsg[not(is-translation-expr())]`
+ *   - `h:head//bind/@jr:requiredMsg[not(is-translation-expr())]`
+ *   - `h:body//label/text()`
+ *   - `h:body//hint/text()`
+ *
+ *   (See notes above for clarification of `is-translation-expr()`.)
+ *
+ * - 'reference': Any XPath **non-translation** expression defined as a label's
+ *   (or hint's) `ref` attribute, i.e.
+ *   - `h:body//label/@ref[not(is-translation-expr())]`
+ *   - `h:body//hint/@ref[not(is-translation-expr())]`
+ *
+ *   (See notes above for clarification of `is-translation-expr()`.)
+ *
+ * @todo It's unclear whether this will all become simpler or more compelex when
+ * we add support for outputs in translations. In theory, the actual translation
+ * `<text>` nodes map quite well to the `TextRange` concept (i.e. they are a
+ * range of static and output chunks, just like labels and hints). The potential
+ * for complications arise from XPath implementation details being largely
+ * opaque (as in, the `jr:itext` implementation is encapsulated in the `xpath`
+ * package, and the engine doesn't really deal with itext translations at the
+ * node level at all).
+ */
+// prettier-ignore
+export type TextChunkSource =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| 'output'
+	| 'reference'
+	| 'translation'
+	| 'static';
 
 /**
  * @todo This (and everything else to do with {@link TextRange}s is for
@@ -23,6 +86,39 @@ export interface TextChunk {
 	get formatted(): unknown;
 }
 
+// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+export type ElementTextRole = 'hint' | 'label' | 'item-label';
+export type ValidationTextRole = 'constraintMsg' | 'requiredMsg';
+export type TextRole = ElementTextRole | ValidationTextRole;
+
+/**
+ * Specifies the origin of a {@link TextRange}.
+ *
+ * - 'form': text is computed from the form definition, as specified for the
+ *   {@link TextRole}. User-facing clients should present text with this origin
+ *   where appropriate.
+ *
+ * - 'form-derived': the form definition lacks a text definition for the
+ *   {@link TextRole}, but an appropriate one has been derived from a related
+ *   (and semantically appropriate) aspect of the form (example: a select item
+ *   without a label may derive that label from the item's value). User-facing
+ *   clients should generally present text with this origin where provided; this
+ *   origin clarifies the source of such text.
+ *
+ * - 'engine': the form definition lacks a definition for the {@link TextRole},
+ *   but provides a constant default in its absence. User facing clients may
+ *   disregard these constant text values, or may use them where a sensible
+ *   default is desired. Clients may also use these constants as keys for
+ *   translation purposes, as appropriate. Non-user facing clients may reference
+ *   these constants for e.g. testing purposes.
+ */
+// prettier-ignore
+export type TextOrigin =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| 'form'
+	| 'form-derived'
+	| 'engine';
+
 /**
  * Represents aspects of a form which produce text, which _might_ be:
  *
@@ -53,7 +149,8 @@ export interface TextChunk {
  * a text range's role may correspond to the "short" or "guidance" `form` of a
  * {@link https://getodk.github.io/xforms-spec/#languages | translation}).
  */
-export interface TextRange<Role extends string | null = null> {
+export interface TextRange<Role extends TextRole, Origin extends TextOrigin = TextOrigin> {
+	readonly origin: Origin;
 	readonly role: Role;
 
 	[Symbol.iterator](): Iterable<TextChunk>;

package/src/client/constants.ts

@@ -0,0 +1,10 @@
+import type { ValidationTextRole } from './TextRange.ts';
+
+export const VALIDATION_TEXT = {
+	constraintMsg: 'Condition not satisfied: constraint',
+	requiredMsg: 'Condition not satisfied: required',
+} as const satisfies Record<ValidationTextRole, string>;
+
+type ValidationTextDefaults = typeof VALIDATION_TEXT;
+
+export type ValidationTextDefault<Role extends ValidationTextRole> = ValidationTextDefaults[Role];

package/src/client/hierarchy.ts

@@ -1,17 +1,41 @@
 import type { ExpandUnion } from '@getodk/common/types/helpers.d.ts';
 import type { GroupNode } from './GroupNode.ts';
-import type { RepeatInstanceNode } from './RepeatInstanceNode.ts';
-import type { RepeatRangeNode } from './RepeatRangeNode.ts';
+import type { ModelValueNode } from './ModelValueNode.ts';
+import type { NoteNode } from './NoteNode.ts';
+import type { RepeatInstanceNode } from './repeat/RepeatInstanceNode.ts';
+import type { RepeatRangeControlledNode } from './repeat/RepeatRangeControlledNode.ts';
+import type { RepeatRangeUncontrolledNode } from './repeat/RepeatRangeUncontrolledNode.ts';
 import type { RootNode } from './RootNode.ts';
 import type { SelectNode } from './SelectNode.ts';
 import type { StringNode } from './StringNode.ts';
 import type { SubtreeNode } from './SubtreeNode.ts';
 
 // prettier-ignore
-export type AnyLeafNode =
+export type AnyControlNode =
+	| NoteNode
 	| SelectNode
 	| StringNode;
 
+// prettier-ignore
+export type AnyLeafNode =
+	| AnyControlNode
+	| ModelValueNode;
+
+// prettier-ignore
+export type RepeatRangeNode =
+	| RepeatRangeControlledNode
+	| RepeatRangeUncontrolledNode;
+
+/**
+ * Any of the concrete node types which may be a parent of non-repeat instance
+ * child nodes.
+ */
+export type GeneralParentNode =
+	| RootNode // eslint-disable-line @typescript-eslint/sort-type-constituents
+	| SubtreeNode
+	| GroupNode
+	| RepeatInstanceNode;
+
 /**
  * Any of the concrete node types which may be a parent of any other node.
  *
@@ -21,12 +45,10 @@ export type AnyLeafNode =
  * - Repeat instances should (continue to) specify {@link RepeatRangeNode}.
  * - All other child nodes should specify {@link GeneralParentNode}.
  */
+// prettier-ignore
 export type AnyParentNode =
-	| RootNode // eslint-disable-line @typescript-eslint/sort-type-constituents
-	| SubtreeNode
-	| GroupNode
-	| RepeatRangeNode
-	| RepeatInstanceNode;
+	| GeneralParentNode
+	| RepeatRangeNode;
 
 /**
  * Any of the concrete node types a client may get from the engine's form
@@ -38,12 +60,6 @@ export type AnyParentNode =
  */
 export type AnyNode = ExpandUnion<AnyLeafNode | AnyParentNode>;
 
-/**
- * Any of the concrete node types which may be a parent of non-repeat instance
- * child nodes.
- */
-export type GeneralParentNode = Exclude<AnyParentNode, RepeatRangeNode>;
-
 /**
  * Any of the concrete node types which may be a child of any other node.
  *

package/src/client/node-types.ts

@@ -1,10 +1,17 @@
+// prettier-ignore
+export type RepeatRangeNodeType =
+	| 'repeat-range:controlled'
+	| 'repeat-range:uncontrolled'
+
 // prettier-ignore
 export type InstanceNodeType =
 	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
 	| 'root'
-	| 'repeat-range'
+	| RepeatRangeNodeType
 	| 'repeat-instance'
 	| 'group'
 	| 'subtree'
+	| 'model-value'
+	| 'note'
 	| 'select'
 	| 'string';

package/src/client/{RepeatRangeNode.ts → repeat/BaseRepeatRangeNode.ts}

@@ -1,12 +1,14 @@
-import type { RepeatRangeDefinition } from '../model/RepeatRangeDefinition.ts';
-import type { BaseNode, BaseNodeState } from './BaseNode.ts';
-import type { NodeAppearances } from './NodeAppearances.ts';
+import type { AnyRepeatRangeDefinition } from '../../model/RepeatRangeDefinition.ts';
+import type { BaseNode, BaseNodeState } from '../BaseNode.ts';
+import type { NodeAppearances } from '../NodeAppearances.ts';
+import type { RootNode } from '../RootNode.ts';
+import type { TextRange } from '../TextRange.ts';
+import type { GeneralParentNode } from '../hierarchy.ts';
+import type { RepeatRangeNodeType } from '../node-types.ts';
+import type { AncestorNodeValidationState } from '../validation.ts';
 import type { RepeatInstanceNode } from './RepeatInstanceNode.ts';
-import type { RootNode } from './RootNode.ts';
-import type { TextRange } from './TextRange.ts';
-import type { GeneralParentNode } from './hierarchy.ts';
 
-export interface RepeatRangeNodeState extends BaseNodeState {
+export interface BaseRepeatRangeNodeState extends BaseNodeState {
 	get hint(): null;
 	get label(): TextRange<'label'> | null;
 
@@ -16,7 +18,7 @@ export interface RepeatRangeNodeState extends BaseNodeState {
 	 * Note: the web-forms engine's representation of this structure differs from
 	 * the underlying XForms specification's primary instance structure.
 	 *
-	 * @see {@link RepeatRangeNode} for additional detail.
+	 * @see {@link BaseRepeatRangeNode} for additional detail.
 	 */
 	get children(): readonly RepeatInstanceNode[];
 
@@ -24,12 +26,12 @@ export interface RepeatRangeNodeState extends BaseNodeState {
 	get value(): null;
 }
 
-export type RepeatRangeNodeAppearances = NodeAppearances<RepeatRangeDefinition>;
+export type RepeatRangeNodeAppearances = NodeAppearances<AnyRepeatRangeDefinition>;
 
 /**
  * Represents a contiguous set of zero or more {@link RepeatInstanceNode}s
  * (accessed by its
- * {@link RepeatRangeNodeState.children | `currentState.children`}).
+ * {@link BaseRepeatRangeNodeState.children | `currentState.children`}).
  *
  * This structure is modeled as a node, like any other, in the web-forms engine
  * representation, which notably differs from the corresponding structure in the
@@ -88,17 +90,14 @@ export type RepeatRangeNodeAppearances = NodeAppearances<RepeatRangeDefinition>;
  * Importantly, if the state of a given repeat range has no instances, no aspect
  * of these repeats will be present in the underlying XForms primary instance
  * state, but the web-forms engine's representations **retains a reference** to
- * its {@link RepeatRangeNode}.
+ * its {@link BaseRepeatRangeNode}.
  */
-export interface RepeatRangeNode extends BaseNode {
-	readonly nodeType: 'repeat-range';
+export interface BaseRepeatRangeNode extends BaseNode {
+	readonly nodeType: RepeatRangeNodeType;
 	readonly appearances: RepeatRangeNodeAppearances;
-	readonly definition: RepeatRangeDefinition;
+	readonly definition: AnyRepeatRangeDefinition;
 	readonly root: RootNode;
 	readonly parent: GeneralParentNode;
-	readonly currentState: RepeatRangeNodeState;
-
-	addInstances(afterIndex?: number, count?: number): RootNode;
-
-	removeInstances(startIndex: number, count?: number): RootNode;
+	readonly currentState: BaseRepeatRangeNodeState;
+	readonly validationState: AncestorNodeValidationState;
 }

package/src/client/{RepeatInstanceNode.ts → repeat/RepeatInstanceNode.ts}

@@ -1,10 +1,11 @@
-import type { RepeatInstanceDefinition } from '../model/RepeatInstanceDefinition.ts';
-import type { RepeatTemplateDefinition } from '../model/RepeatTemplateDefinition.ts';
-import type { BaseNode, BaseNodeState } from './BaseNode.ts';
-import type { NodeAppearances } from './NodeAppearances.ts';
-import type { RepeatRangeNode } from './RepeatRangeNode.ts';
-import type { RootNode } from './RootNode.ts';
-import type { GeneralChildNode } from './hierarchy.ts';
+import type { RepeatInstanceDefinition } from '../../model/RepeatInstanceDefinition.ts';
+import type { RepeatTemplateDefinition } from '../../model/RepeatTemplateDefinition.ts';
+import type { BaseNode, BaseNodeState } from '../BaseNode.ts';
+import type { GeneralChildNode, RepeatRangeNode } from '../hierarchy.ts';
+import type { NodeAppearances } from '../NodeAppearances.ts';
+import type { RootNode } from '../RootNode.ts';
+import type { AncestorNodeValidationState } from '../validation.ts';
+import type { BaseRepeatRangeNode } from './BaseRepeatRangeNode.ts';
 
 export interface RepeatInstanceNodeState extends BaseNodeState {
 	// TODO(?): Previous iteration included an `index` getter here. I don't see it
@@ -37,9 +38,10 @@ export interface RepeatInstanceNode extends BaseNode {
 	 * Note: the web-forms engine's representation of this structure differs from
 	 * the underlying XForms specification's primary instance structure.
 	 *
-	 * @see {@link RepeatRangeNode} for additional detail.
+	 * @see {@link BaseRepeatRangeNode} for additional detail.
 	 */
 	readonly parent: RepeatRangeNode;
 
 	readonly currentState: RepeatInstanceNodeState;
+	readonly validationState: AncestorNodeValidationState;
 }

package/src/client/repeat/RepeatRangeControlledNode.ts

@@ -0,0 +1,20 @@
+import type { ControlledRepeatRangeDefinition } from '../../model/RepeatRangeDefinition.ts';
+import type { BaseRepeatRangeNode, BaseRepeatRangeNodeState } from './BaseRepeatRangeNode.ts';
+import type { RepeatRangeUncontrolledNode } from './RepeatRangeUncontrolledNode.ts';
+
+/**
+ * {@inheritDoc BaseRepeatRangeNodeState}
+ * @see {@link BaseRepeatRangeNodeState}
+ */
+export interface RepeatRangeControlledState extends BaseRepeatRangeNodeState {}
+
+/**
+ * Represents a repeat range whose repeat instances are controlled by the
+ * engine, and cannot be added or removed by a client. Functionality and
+ * semantics are otherwise consistent with an [uncontrolled]
+ * {@link RepeatRangeUncontrolledNode}.
+ */
+export interface RepeatRangeControlledNode extends BaseRepeatRangeNode {
+	readonly nodeType: 'repeat-range:controlled';
+	readonly definition: ControlledRepeatRangeDefinition;
+}

package/src/client/repeat/RepeatRangeUncontrolledNode.ts

@@ -0,0 +1,21 @@
+import type { UncontrolledRepeatRangeDefinition } from '../../model/RepeatRangeDefinition.ts';
+import type { RootNode } from '../RootNode.ts';
+import type { BaseRepeatRangeNode, BaseRepeatRangeNodeState } from './BaseRepeatRangeNode.ts';
+
+/**
+ * {@inheritDoc BaseRepeatRangeNodeState}
+ * @see {@link BaseRepeatRangeNodeState}
+ */
+export interface RepeatRangeUncontrolledState extends BaseRepeatRangeNodeState {}
+
+/**
+ * {@inheritDoc BaseRepeatRangeNode}
+ * @see {@link BaseRepeatRangeNode}
+ */
+export interface RepeatRangeUncontrolledNode extends BaseRepeatRangeNode {
+	readonly nodeType: 'repeat-range:uncontrolled';
+	readonly definition: UncontrolledRepeatRangeDefinition;
+
+	addInstances(afterIndex?: number, count?: number): RootNode;
+	removeInstances(startIndex: number, count?: number): RootNode;
+}

package/src/client/validation.ts

@@ -0,0 +1,199 @@
+import type { NodeID } from '../instance/identity.ts';
+import type { BaseNode, BaseNodeState } from './BaseNode.ts';
+import type { OpaqueReactiveObjectFactory } from './OpaqueReactiveObjectFactory.ts';
+import type { RootNode } from './RootNode.ts';
+import type { TextRange } from './TextRange.ts';
+
+// This interface exists so that extensions can share JSDoc for `valid`.
+interface BaseValidity {
+	/**
+	 * Specifies the unambiguous validity state for each validity condition of a
+	 * given node, or for the derived validity of any parent node whose descendants
+	 * are validated.
+	 *
+	 * For {@link ValidationCondition | form-defined conditions}, validity is
+	 * determined as follows:
+	 *
+	 *
+	 *   expression | state     |  blank  | non-blank
+	 * ------------:|:----------|:-------:|:---------:
+	 * `constraint` | `true`\*  | ✅      | ✅
+	 * `constraint` | `false`   | ✅      | ❌
+	 * `required`   | `false`\* | ✅      | ✅
+	 * `required`   | `true`    | ❌      | ✅
+	 *
+	 * - \* = default (expression not defined)
+	 * - ✅ = `valid: true`
+	 * - ❌ = `valid: false`
+	 */
+	readonly valid: boolean;
+}
+
+/**
+ * Form-defined conditions which determine node validity.
+ *
+ * @see {@link https://getodk.github.io/xforms-spec/#bind-attributes | `constraint` and `required` bind attributes}
+ */
+export type ValidationCondition = 'constraint' | 'required';
+
+interface ValidationConditionMessageRoles {
+	readonly constraint: 'constraintMsg';
+	readonly required: 'requiredMsg';
+}
+
+export type ValidationConditionMessageRole<Condition extends ValidationCondition> =
+	ValidationConditionMessageRoles[Condition];
+
+/**
+ * Source of a condition's violation message.
+ *
+ * - Form-defined messages (specified by the
+ *   {@link https://getodk.github.io/xforms-spec/#bind-attributes | `jr:constraintMsg` and `jr:requiredMsg`}
+ *   attributes) will be favored when provided by the form, and will be
+ *   translated according to the form's active language (where applicable).
+ *
+ * - Otherwise, an engine-defined message will be provided as a fallback. This
+ *   fallback is provided mainly for API consistency, and may be referenced for
+ *   testing purposes; user-facing clients are expected to provide fallback
+ *   messaging language most appropriate for their user neeeds. Engine-defined
+ *   fallback messages **are not translated**. They are intended to be used, if
+ *   at all, as sentinel values when a form-defined message is not available.
+ */
+// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+export type ViolationMessageSource = 'form' | 'engine';
+
+/**
+ * @see {@link ViolationMessage.asString}
+ */
+// prettier-ignore
+type ViolationMessageAsString<
+	Source extends ViolationMessageSource,
+	Condition extends ValidationCondition,
+> =
+	Source extends 'form'
+		? string
+		: `Condition not satisfied: ${Condition}`;
+
+/**
+ * A violation message is provided for every violation of a form-defined
+ * {@link ValidationCondition}.
+ */
+export interface ViolationMessage<
+	Condition extends ValidationCondition,
+	Source extends ViolationMessageSource = ViolationMessageSource,
+> extends TextRange<ValidationConditionMessageRole<Condition>> {
+	/**
+	 * - Form-defined violation messages may produce arbitrary text. This text may
+	 *   be translated
+	 *   ({@link https://getodk.github.io/xforms-spec/#fn:jr:itext | `jr:itext`}),
+	 *   and it may be dynamic (translations may reference form state with
+	 *   {@link https://getodk.github.io/xforms-spec/#body-elements | `<output>`}).
+	 *
+	 * - When a form-defined violation message is not available, an engine-defined
+	 *   message will be provided in its place. Engine-defined violation messages
+	 *   are statically defined (and therefore not presently translated by the
+	 *   engine). Their static value can also be referenced as a static type, by
+	 *   checking {@link isFallbackMessage}.
+	 */
+	get asString(): ViolationMessageAsString<Source, Condition>;
+}
+
+export interface ConditionSatisfied<Condition extends ValidationCondition> extends BaseValidity {
+	readonly condition: Condition;
+	readonly valid: true;
+	readonly message: null;
+}
+
+export interface ConditionViolation<Condition extends ValidationCondition> extends BaseValidity {
+	readonly condition: Condition;
+	readonly valid: false;
+	readonly message: ViolationMessage<Condition>;
+}
+
+export type ConditionValidation<Condition extends ValidationCondition> =
+	| ConditionSatisfied<Condition>
+	| ConditionViolation<Condition>;
+
+export type AnyViolation = ConditionViolation<ValidationCondition>;
+
+/**
+ * Represents the validation state of a leaf (or value) node.
+ *
+ * Validity is computed for two conditions:
+ *
+ * - {@link constraint}: arbitrary form-defined condition which specifies
+ *   whether a (non-blank) value is considered valid
+ *
+ *  - {@link required}: when a node is required, the node must have a non-blank
+ *    value to be considered valid
+ *
+ * Only one of these conditions can be violated (applicability is mutually
+ * exclusive). As such, {@link violation} provides a convenient way to determine
+ * whether a leaf/value node is valid with a single (null) check.
+ *
+ * @see {@link BaseValidity.valid} for additional details on how these
+ * conditions are evaluated (and how they interact with one another).
+ */
+export interface LeafNodeValidationState {
+	get constraint(): ConditionValidation<'constraint'>;
+	get required(): ConditionValidation<'required'>;
+
+	/**
+	 * Violations are mutually exclusive:
+	 *
+	 * - {@link constraint} can only be violated by a non-blank value
+	 * - {@link required} can only be violated by a blank value
+	 *
+	 * As such, at most one violation can be present. If none is present,
+	 * the node is considered valid.
+	 */
+	get violation(): AnyViolation | null;
+}
+
+/**
+ * Provides a reference to any leaf/value node which currently violates either
+ * of its validity conditions.
+ *
+ * Any client can safely assume:
+ *
+ * - {@link nodeId} will be a stable reference to a node with the same
+ *   {@link BaseNode.nodeId | `nodeId`}.
+ *
+ * - {@link node} will have reference equality to the same node object, within
+ *   the active form instance's {@link RootNode} tree
+ *
+ * - {@link reference} will be a **current** reference to the same node object's
+ *   **computed** {@link BaseNodeState.reference | `currentState.reference`}
+ *
+ * Any client utilizing the engine's reactive APIs (having provided an
+ * {@link OpaqueReactiveObjectFactory}) can safely assume that {@link reference}
+ * will be recomputed and updated in tandem with the affected node's own
+ * computed `currentState.reference` as well.
+ *
+ * @todo this type currently exposes multiple ways to reference the affected
+ * node. This is intended to maximize flexibility: it's not yet clear how
+ * clients will be best served by which reference mechanism. It is expected that
+ * each property will be directly computed from the affected node.
+ */
+export interface DescendantNodeViolationReference {
+	readonly nodeId: NodeID;
+
+	get reference(): string;
+	get violation(): AnyViolation;
+}
+
+/**
+ * Provides access from any ancestor/parent node, to identify any validity
+ * violations present on any of its leaf/value node descendants.
+ *
+ * @see {@link DescendantNodeViolationReference} for details on how descendants
+ * may be referenced when such a violation is present.
+ */
+export interface AncestorNodeValidationState {
+	get violations(): readonly DescendantNodeViolationReference[];
+}
+
+// prettier-ignore
+export type NodeValidationState =
+	| AncestorNodeValidationState
+	| LeafNodeValidationState;