@getodk/xforms-engine 0.2.0 → 0.4.0

package/dist/client/repeat/RepeatRangeControlledNode.d.ts

@@ -0,0 +1,18 @@
+import { ControlledRepeatRangeDefinition } from '../../parse/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,19 @@
+import { UncontrolledRepeatRangeDefinition } from '../../parse/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/unsupported/RangeNode.d.ts

@@ -0,0 +1,9 @@
+import { RangeControlDefinition } from '../../parse/body/control/RangeControlDefinition.ts';
+import { UnsupportedControlDefinition, UnsupportedControlNode } from './UnsupportedControlNode.ts';
+export interface RangeNodeDefinition extends UnsupportedControlDefinition {
+    readonly bodyElement: RangeControlDefinition;
+}
+export interface RangeNode extends UnsupportedControlNode {
+    readonly nodeType: 'range';
+    readonly definition: RangeNodeDefinition;
+}

package/dist/client/unsupported/RankNode.d.ts

@@ -0,0 +1,9 @@
+import { RankControlDefinition } from '../../parse/body/control/RankControlDefinition.ts';
+import { UnsupportedControlDefinition, UnsupportedControlNode } from './UnsupportedControlNode.ts';
+export interface RankNodeDefinition extends UnsupportedControlDefinition {
+    readonly bodyElement: RankControlDefinition;
+}
+export interface RankNode extends UnsupportedControlNode {
+    readonly nodeType: 'rank';
+    readonly definition: RankNodeDefinition;
+}

package/dist/client/unsupported/UnsupportedControlNode.d.ts

@@ -0,0 +1,32 @@
+import { UnknownAppearanceDefinition } from '../../parse/body/appearance/unknownAppearanceParser.ts';
+import { RangeControlDefinition } from '../../parse/body/control/RangeControlDefinition.ts';
+import { RankControlDefinition } from '../../parse/body/control/RankControlDefinition.ts';
+import { UploadControlDefinition } from '../../parse/body/control/UploadControlDefinition.ts';
+import { LeafNodeDefinition } from '../../parse/model/LeafNodeDefinition.ts';
+import { BaseNode, BaseNodeState } from '../BaseNode.ts';
+import { RootNode } from '../RootNode.ts';
+import { GeneralParentNode } from '../hierarchy.ts';
+import { UnsupportedControlNodeType } from '../node-types.ts';
+import { LeafNodeValidationState } from '../validation.ts';
+export interface UnsupportedControlNodeState extends BaseNodeState {
+    get children(): null;
+    get valueOptions(): unknown;
+    get value(): unknown;
+}
+export type UnsupportedControlElementDefinition = RangeControlDefinition | RankControlDefinition | UploadControlDefinition;
+export interface UnsupportedControlDefinition extends LeafNodeDefinition {
+    readonly bodyElement: UnsupportedControlElementDefinition;
+}
+/**
+ * Stub node, for form controls pending further engine support.
+ */
+export interface UnsupportedControlNode extends BaseNode {
+    readonly nodeType: UnsupportedControlNodeType;
+    readonly appearances: UnknownAppearanceDefinition;
+    readonly definition: UnsupportedControlDefinition;
+    readonly root: RootNode;
+    readonly parent: GeneralParentNode;
+    readonly currentState: UnsupportedControlNodeState;
+    readonly validationState: LeafNodeValidationState;
+    setValue?(value: never): never;
+}

package/dist/client/unsupported/UploadNode.d.ts

@@ -0,0 +1,9 @@
+import { UploadControlDefinition } from '../../parse/body/control/UploadControlDefinition.ts';
+import { UnsupportedControlDefinition, UnsupportedControlNode } from './UnsupportedControlNode.ts';
+export interface UploadNodeDefinition extends UnsupportedControlDefinition {
+    readonly bodyElement: UploadControlDefinition;
+}
+export interface UploadNode extends UnsupportedControlNode {
+    readonly nodeType: 'upload';
+    readonly definition: UploadNodeDefinition;
+}

package/dist/client/validation.d.ts

@@ -0,0 +1,162 @@
+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/index.d.ts

@@ -1,17 +1,25 @@
 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, AnyUnsupportedControlNode, 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 { AnySelectDefinition, SelectDefinition, } from './body/control/select/SelectDefinition.ts';
+export type * from './client/TriggerNode.ts';
+export type * from './client/unsupported/RangeNode.ts';
+export type * from './client/unsupported/RankNode.ts';
+export type * from './client/unsupported/UploadNode.ts';
+export type * from './client/validation.ts';
+export type { AnySelectDefinition, SelectDefinition, } from './parse/body/control/select/SelectDefinition.ts';