@getodk/xforms-engine 0.2.0 → 0.3.0

package/dist/client/{RepeatRangeNode.d.ts → repeat/BaseRepeatRangeNode.d.ts}

@@ -1,12 +1,14 @@
-import { RepeatRangeDefinition } from '../model/RepeatRangeDefinition.ts';
-import { BaseNode, BaseNodeState } from './BaseNode.ts';
-import { NodeAppearances } from './NodeAppearances.ts';
+import { AnyRepeatRangeDefinition } from '../../model/RepeatRangeDefinition.ts';
+import { BaseNode, BaseNodeState } from '../BaseNode.ts';
+import { NodeAppearances } from '../NodeAppearances.ts';
+import { RootNode } from '../RootNode.ts';
+import { TextRange } from '../TextRange.ts';
+import { GeneralParentNode } from '../hierarchy.ts';
+import { RepeatRangeNodeType } from '../node-types.ts';
+import { AncestorNodeValidationState } from '../validation.ts';
 import { RepeatInstanceNode } from './RepeatInstanceNode.ts';
-import { RootNode } from './RootNode.ts';
-import { TextRange } from './TextRange.ts';
-import { GeneralParentNode } from './hierarchy.ts';
 
-export interface RepeatRangeNodeState extends BaseNodeState {
+export interface BaseRepeatRangeNodeState extends BaseNodeState {
     get hint(): null;
     get label(): TextRange<'label'> | null;
     /**
@@ -15,17 +17,17 @@ 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[];
     get valueOptions(): null;
     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
@@ -84,15 +86,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/dist/client/{RepeatInstanceNode.d.ts → repeat/RepeatInstanceNode.d.ts}

@@ -1,10 +1,10 @@
-import { RepeatInstanceDefinition } from '../model/RepeatInstanceDefinition.ts';
-import { RepeatTemplateDefinition } from '../model/RepeatTemplateDefinition.ts';
-import { BaseNode, BaseNodeState } from './BaseNode.ts';
-import { NodeAppearances } from './NodeAppearances.ts';
-import { RepeatRangeNode } from './RepeatRangeNode.ts';
-import { RootNode } from './RootNode.ts';
-import { GeneralChildNode } from './hierarchy.ts';
+import { RepeatInstanceDefinition } from '../../model/RepeatInstanceDefinition.ts';
+import { RepeatTemplateDefinition } from '../../model/RepeatTemplateDefinition.ts';
+import { BaseNode, BaseNodeState } from '../BaseNode.ts';
+import { GeneralChildNode, RepeatRangeNode } from '../hierarchy.ts';
+import { NodeAppearances } from '../NodeAppearances.ts';
+import { RootNode } from '../RootNode.ts';
+import { AncestorNodeValidationState } from '../validation.ts';
 
 export interface RepeatInstanceNodeState extends BaseNodeState {
     get hint(): null;
@@ -25,8 +25,9 @@ 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/dist/client/repeat/RepeatRangeControlledNode.d.ts

@@ -0,0 +1,19 @@
+import { ControlledRepeatRangeDefinition } from '../../model/RepeatRangeDefinition.ts';
+import { BaseRepeatRangeNode, BaseRepeatRangeNodeState } from './BaseRepeatRangeNode.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/dist/client/repeat/RepeatRangeUncontrolledNode.d.ts

@@ -0,0 +1,20 @@
+import { UncontrolledRepeatRangeDefinition } from '../../model/RepeatRangeDefinition.ts';
+import { RootNode } from '../RootNode.ts';
+import { 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/dist/client/validation.d.ts

@@ -0,0 +1,163 @@
+import { NodeID } from '../instance/identity.ts';
+import { TextRange } from './TextRange.ts';
+
+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.
+ */
+export type ViolationMessageSource = 'form' | 'engine';
+/**
+ * @see {@link ViolationMessage.asString}
+ */
+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[];
+}
+export type NodeValidationState = AncestorNodeValidationState | LeafNodeValidationState;
+export {};

package/dist/expression/DependentExpression.d.ts

@@ -1,9 +1,11 @@
 import { XFormsXPathEvaluator } from '@getodk/xpath';
+import { ConstantExpression, ConstantTruthyExpression } from '../parse/xpath/semantic-analysis.ts';
 import { DependencyContext } from './DependencyContext.ts';
 
 declare const evaluatorMethodsByResultType: {
     readonly boolean: "evaluateBoolean";
     readonly nodes: "evaluateNodes";
+    readonly number: "evaluateNumber";
     readonly string: "evaluateString";
 };
 type EvaluatorMethodsByResultType = typeof evaluatorMethodsByResultType;
@@ -11,10 +13,6 @@ export type DependentExpressionResultType = keyof EvaluatorMethodsByResultType;
 export type DependentExpressionEvaluatorMethod<Type extends DependentExpressionResultType> = EvaluatorMethodsByResultType[Type];
 export type DependentExpressionResult<Type extends DependentExpressionResultType> = ReturnType<XFormsXPathEvaluator[DependentExpressionEvaluatorMethod<Type>]>;
 interface SemanticDependencyOptions {
-    /**
-     * @default false
-     */
-    readonly parentContext?: boolean | undefined;
     /**
      * @default false
      */
@@ -25,19 +23,25 @@ interface DependentExpressionOptions {
      * @default false
      */
     readonly ignoreContextReference?: boolean;
-    /**
-     * @default true
-     */
-    readonly ignoreNullExpressions?: boolean;
     readonly semanticDependencies?: SemanticDependencyOptions;
 }
+export interface ConstantDependentExpression<Type extends DependentExpressionResultType> extends DependentExpression<Type> {
+    readonly expression: ConstantExpression;
+}
+export interface ConstantTruthyDependentExpression extends ConstantDependentExpression<'boolean'> {
+    readonly expression: ConstantTruthyExpression;
+}
 export declare class DependentExpression<Type extends DependentExpressionResultType> {
     readonly resultType: Type;
     readonly expression: string;
     readonly dependencyReferences: ReadonlySet<string>;
     readonly isTranslated: boolean;
     readonly evaluatorMethod: DependentExpressionEvaluatorMethod<Type>;
+    readonly constantExpression: ConstantExpression | null;
+    readonly constantTruthyExpression: ConstantTruthyExpression | null;
     constructor(context: DependencyContext, resultType: Type, expression: string, options?: DependentExpressionOptions);
+    isConstantExpression(): this is ConstantDependentExpression<Type>;
+    isConstantTruthyExpression(): this is ConstantTruthyDependentExpression;
     toString(): string | null;
 }
 export type AnyDependentExpression = DependentExpression<any>;

package/dist/index.d.ts

@@ -1,17 +1,22 @@
 import { InitializeForm } from './index.ts';
 
 export declare const initializeForm: InitializeForm;
+export * as constants from './client/constants.ts';
 export type * from './client/EngineConfig.ts';
 export type * from './client/FormLanguage.ts';
 export type * from './client/GroupNode.ts';
+export type { AnyChildNode, AnyControlNode, AnyLeafNode, AnyNode, AnyParentNode, GeneralChildNode, GeneralParentNode, RepeatRangeNode, } from './client/hierarchy.ts';
+export type * from './client/index.ts';
+export type * from './client/ModelValueNode.ts';
+export type * from './client/NoteNode.ts';
 export type * from './client/OpaqueReactiveObjectFactory.ts';
-export type * from './client/RepeatInstanceNode.ts';
-export type * from './client/RepeatRangeNode.ts';
+export type * from './client/repeat/RepeatInstanceNode.ts';
+export type * from './client/repeat/RepeatRangeControlledNode.ts';
+export type * from './client/repeat/RepeatRangeUncontrolledNode.ts';
 export type * from './client/RootNode.ts';
 export type * from './client/SelectNode.ts';
 export type * from './client/StringNode.ts';
 export type * from './client/SubtreeNode.ts';
 export type * from './client/TextRange.ts';
-export type { AnyChildNode, AnyLeafNode, AnyNode, AnyParentNode, GeneralChildNode, GeneralParentNode, } from './client/hierarchy.ts';
-export type * from './client/index.ts';
+export type * from './client/validation.ts';
 export type { AnySelectDefinition, SelectDefinition, } from './body/control/select/SelectDefinition.ts';