@getodk/xforms-engine 0.5.0 → 0.7.0

package/README.md

@@ -3,7 +3,7 @@
 Implementation of the [ODK XForms specification](https://getodk.github.io/xforms-spec/)'s data model and computation logic. This package does not handle presentation or user interaction. Those aspects of forms are meant to be handled by a client. Presently, those clients are:
 
 - [`@getodk/web-forms`](../web-forms)
-- [`@getodk/ui-solid`](../ui-solid)
+- [`@getodk/scenario`](../scenario)
 
 ## Install
 

package/dist/client/BaseNode.d.ts

@@ -3,7 +3,7 @@ import { NodeAppearances } from './NodeAppearances.ts';
 import { TextRange } from './TextRange.ts';
 import { FormNodeID } from './identity.ts';
 import { InstanceNodeType } from './node-types.ts';
-import { SubmissionState } from './submission/SubmissionState.ts';
+import { InstanceState } from './serialization/InstanceState.ts';
 import { NodeValidationState } from './validation.ts';
 export interface BaseNodeState {
     /**
@@ -133,6 +133,10 @@ export interface BaseNode {
      * @see {@link TokenListParser} for details.
      */
     readonly appearances: NodeAppearances<any> | null;
+    /**
+     * A node can have options that determine its behavior.
+     */
+    readonly nodeOptions: object | null;
     /**
      * 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
@@ -207,14 +211,14 @@ export interface BaseNode {
      */
     readonly validationState: NodeValidationState;
     /**
-     * Represents the current submission state of the node.
+     * Represents the current instance state of the node.
      *
-     * @see {@link SubmissionState.submissionXML} for additional detail.
+     * @see {@link InstanceState.instanceXML} for additional detail.
      *
      * @todo Consider whether this can (should) be merged with
      * {@link currentState}, while providing the same client-reactivity
      * guarantees. (The challenge there is in defining client-reactive state which
      * self-referentially derives state from its own definition.)
      */
-    readonly submissionState: SubmissionState;
+    readonly instanceState: InstanceState;
 }

package/dist/client/BaseValueNode.d.ts

@@ -2,23 +2,26 @@ import { LeafNodeDefinition } from '../parse/model/LeafNodeDefinition.ts';
 import { BaseNode, BaseNodeState } from './BaseNode.ts';
 import { GeneralParentNode } from './hierarchy.ts';
 import { LeafNodeType } from './node-types.ts';
+import { InstanceState } from './serialization/InstanceState.ts';
 import { LeafNodeValidationState } from './validation.ts';
 import { ValueType } from './ValueType.ts';
 export interface BaseValueNodeState<Value> extends BaseNodeState {
     get children(): null;
-    get valueOptions(): null;
+    get valueOptions(): unknown;
     get value(): Value;
     /**
      * Reflects the serialized string representation of a {@link BaseValueNode}'s
      * {@link value} state. This representation allows access to the node's value
      * _as primary instance state_. In other words, this is the value which:
      *
-     * - would be serialized as a text node in
-     *   {@link SubmissionState.submissionXML} (note: this value is **NOT**
-     *   escaped for XML serialization, as it is there)
+     * - would be serialized as a text node in {@link InstanceState.instanceXML}
+     *   (note: this value is **NOT** escaped for XML serialization, as it is
+     *   there)
      *
      * - is used when the node's value is referenced in any of a form's XPath
      *   expressions
+     *
+     * @todo Consider moving into {@link InstanceState}
      */
     get instanceValue(): string;
 }
@@ -29,4 +32,5 @@ export interface BaseValueNode<V extends ValueType = ValueType, Value = string>
     readonly parent: GeneralParentNode;
     readonly currentState: BaseValueNodeState<Value>;
     readonly validationState: LeafNodeValidationState;
+    readonly instanceState: InstanceState;
 }

package/dist/client/GroupNode.d.ts

@@ -21,6 +21,7 @@ export type GroupNodeAppearances = NodeAppearances<GroupDefinition>;
 export interface GroupNode extends BaseNode {
     readonly nodeType: 'group';
     readonly appearances: GroupNodeAppearances;
+    readonly nodeOptions: null;
     readonly definition: GroupDefinition;
     readonly root: RootNode;
     readonly parent: GeneralParentNode;

package/dist/client/InputNode.d.ts

@@ -24,15 +24,39 @@ export interface InputDefinition<V extends ValueType = ValueType> extends LeafNo
     readonly bodyElement: InputControlDefinition;
 }
 export type InputNodeAppearances = NodeAppearances<InputDefinition>;
+interface StringInputNodeOptions {
+    readonly rows: number | null;
+}
+interface GeoInputNodeOptions {
+    readonly accuracyThreshold: number | null;
+    readonly unacceptableAccuracyThreshold: number | null;
+}
+interface InputNodeOptionsByValueType {
+    readonly string: StringInputNodeOptions;
+    readonly int: null;
+    readonly boolean: null;
+    readonly decimal: null;
+    readonly date: null;
+    readonly time: null;
+    readonly dateTime: null;
+    readonly geopoint: GeoInputNodeOptions;
+    readonly geotrace: GeoInputNodeOptions;
+    readonly geoshape: GeoInputNodeOptions;
+    readonly binary: null;
+    readonly barcode: null;
+    readonly intent: null;
+}
+export type InputNodeOptions<V extends ValueType> = InputNodeOptionsByValueType[V];
 /**
  * A node corresponding to form field defined as an
  * {@link https://getodk.github.io/xforms-spec/#body-elements | XForms `<input>`},
- * which a user-facing client would likely present for a user to fill..
+ * which a user-facing client would likely present for a user to fill.
  */
 export interface InputNode<V extends ValueType = ValueType> extends BaseValueNode<V, InputValue<V>> {
     readonly nodeType: 'input';
     readonly valueType: V;
     readonly appearances: InputNodeAppearances;
+    readonly nodeOptions: InputNodeOptions<V>;
     readonly definition: InputDefinition<V>;
     readonly root: RootNode;
     readonly parent: GeneralParentNode;
@@ -43,11 +67,16 @@ export interface InputNode<V extends ValueType = ValueType> extends BaseValueNod
      */
     setValue(value: InputNodeInputValue<V>): RootNode;
 }
+export type StringInputValue = InputValue<'string'>;
+export type IntInputValue = InputValue<'int'>;
+export type DecimalInputValue = InputValue<'decimal'>;
+export type GeopointInputValue = InputValue<'geopoint'>;
 export type StringInputNode = InputNode<'string'>;
 export type IntInputNode = InputNode<'int'>;
 export type DecimalInputNode = InputNode<'decimal'>;
-type SupportedInputValueType = 'string' | 'int' | 'decimal';
+export type GeopointInputNode = InputNode<'geopoint'>;
+type SupportedInputValueType = 'string' | 'int' | 'decimal' | 'geopoint';
 type TemporaryStringValueType = Exclude<ValueType, SupportedInputValueType>;
 export type TemporaryStringValueInputNode = InputNode<TemporaryStringValueType>;
-export type AnyInputNode = StringInputNode | IntInputNode | DecimalInputNode | TemporaryStringValueInputNode;
+export type AnyInputNode = StringInputNode | IntInputNode | DecimalInputNode | GeopointInputNode | TemporaryStringValueInputNode;
 export {};

package/dist/client/ModelValueNode.d.ts

@@ -32,6 +32,7 @@ export interface ModelValueNode<V extends ValueType = ValueType> extends BaseVal
     readonly nodeType: 'model-value';
     readonly valueType: V;
     readonly appearances: null;
+    readonly nodeOptions: null;
     readonly definition: ModelValueDefinition<V>;
     readonly root: RootNode;
     readonly parent: GeneralParentNode;

package/dist/client/NoteNode.d.ts

@@ -1,12 +1,15 @@
+import { NoteRuntimeValue } from '../lib/codecs/NoteCodec.ts';
 import { InputControlDefinition } from '../parse/body/control/InputControlDefinition.ts';
 import { LeafNodeDefinition } from '../parse/model/LeafNodeDefinition.ts';
-import { BaseNode, BaseNodeState } from './BaseNode.ts';
+import { BaseValueNode, BaseValueNodeState } from './BaseValueNode.ts';
 import { GeneralParentNode } from './hierarchy.ts';
 import { NodeAppearances } from './NodeAppearances.ts';
 import { RootNode } from './RootNode.ts';
 import { TextRange } from './TextRange.ts';
 import { LeafNodeValidationState } from './validation.ts';
-export interface NoteNodeState extends BaseNodeState {
+import { ValueType } from './ValueType.ts';
+export type NoteValue<V extends ValueType> = NoteRuntimeValue<V>;
+export interface NoteNodeState<V extends ValueType> extends BaseValueNodeState<NoteValue<V>> {
     /**
      * Note-specific specialization: a note will always have a non-null value in
      * at least one of:
@@ -29,9 +32,9 @@ export interface NoteNodeState extends BaseNodeState {
     /**
      * Reflects the readonly value of a {@link NoteNode}, or `null` if blank.
      */
-    get value(): string | null;
+    get value(): NoteValue<V>;
 }
-export interface NoteDefinition extends LeafNodeDefinition {
+export interface NoteDefinition<V extends ValueType = ValueType> extends LeafNodeDefinition<V> {
     readonly bodyElement: InputControlDefinition;
 }
 export type NoteNodeAppearances = NodeAppearances<NoteDefinition>;
@@ -41,12 +44,26 @@ export type NoteNodeAppearances = NodeAppearances<NoteDefinition>;
  * - associated with an input, with at least one text element (label or hint)
  * - guaranteed to be {@link NoteNodeState.readonly | readonly}
  */
-export interface NoteNode extends BaseNode {
+export interface NoteNode<V extends ValueType = ValueType> extends BaseValueNode<V, NoteValue<V>> {
     readonly nodeType: 'note';
     readonly appearances: NoteNodeAppearances;
-    readonly definition: NoteDefinition;
+    readonly nodeOptions: null;
+    readonly definition: NoteDefinition<V>;
     readonly root: RootNode;
     readonly parent: GeneralParentNode;
-    readonly currentState: NoteNodeState;
+    readonly currentState: NoteNodeState<V>;
     readonly validationState: LeafNodeValidationState;
 }
+export type StringNoteValue = NoteValue<'string'>;
+export type IntNoteValue = NoteValue<'int'>;
+export type DecimalNoteValue = NoteValue<'decimal'>;
+export type GeopointNoteValue = NoteValue<'geopoint'>;
+export type StringNoteNode = NoteNode<'string'>;
+export type IntNoteNode = NoteNode<'int'>;
+export type DecimalNoteNode = NoteNode<'decimal'>;
+export type GeopointNoteNode = NoteNode<'geopoint'>;
+type SupportedNoteValueType = 'string' | 'int' | 'decimal' | 'geopoint';
+type TemporaryStringValueType = Exclude<ValueType, SupportedNoteValueType>;
+export type TemporaryStringValueNoteNode = NoteNode<TemporaryStringValueType>;
+export type AnyNoteNode = StringNoteNode | IntNoteNode | DecimalNoteNode | GeopointNoteNode | TemporaryStringValueNoteNode;
+export {};

package/dist/client/RangeNode.d.ts

@@ -0,0 +1,36 @@
+import { RuntimeInputValue, RuntimeValue } from '../lib/codecs/getSharedValueCodec.ts';
+import { RangeNodeDefinition, RangeValueType } from '../parse/model/RangeNodeDefinition.ts';
+import { BaseValueNode, BaseValueNodeState } from './BaseValueNode.ts';
+import { NodeAppearances } from './NodeAppearances.ts';
+import { RootNode } from './RootNode.ts';
+import { GeneralParentNode } from './hierarchy.ts';
+import { LeafNodeValidationState } from './validation.ts';
+export type { RangeValueType };
+export type RangeValue<V extends RangeValueType> = RuntimeValue<V>;
+export type RangeInputValue<V extends RangeValueType> = RuntimeInputValue<V>;
+export interface RangeNodeState<V extends RangeValueType> extends BaseValueNodeState<RangeValue<V>> {
+    get valueOptions(): null;
+}
+export type RangeNodeAppearances = NodeAppearances<RangeNodeDefinition>;
+/**
+ * A node corresponding to form field defined as an
+ * {@link https://getodk.github.io/xforms-spec/#body-elements | XForms `<range>`}.
+ */
+export interface RangeNode<V extends RangeValueType = RangeValueType> extends BaseValueNode<V, RangeValue<V>> {
+    readonly nodeType: 'range';
+    readonly valueType: V;
+    readonly appearances: RangeNodeAppearances;
+    readonly nodeOptions: null;
+    readonly definition: RangeNodeDefinition<V>;
+    readonly root: RootNode;
+    readonly parent: GeneralParentNode;
+    readonly currentState: RangeNodeState<V>;
+    readonly validationState: LeafNodeValidationState;
+    /**
+     * For use by a client to update the value of an {@link RangeNode}.
+     */
+    setValue(value: RangeInputValue<V>): RootNode;
+}
+export type IntRangeNode = RangeNode<'int'>;
+export type DecimalRangeNode = RangeNode<'decimal'>;
+export type AnyRangeNode = IntRangeNode | DecimalRangeNode;

package/dist/client/RankNode.d.ts

@@ -0,0 +1,46 @@
+import { RankControlDefinition } from '../parse/body/control/RankControlDefinition.ts';
+import { LeafNodeDefinition } from '../parse/model/LeafNodeDefinition.ts';
+import { BaseValueNode, BaseValueNodeState } from './BaseValueNode.ts';
+import { RootNode } from './RootNode.ts';
+import { TextRange } from './TextRange.ts';
+import { GeneralParentNode } from './hierarchy.ts';
+import { LeafNodeValidationState } from './validation.ts';
+import { UnknownAppearanceDefinition } from '../parse/body/appearance/unknownAppearanceParser.ts';
+import { ValueType } from './ValueType.ts';
+export interface RankItem {
+    get label(): TextRange<'item-label'>;
+    get value(): string;
+}
+export type RankValueOptions = readonly RankItem[];
+export interface RankNodeState extends BaseValueNodeState<readonly string[]> {
+    get valueOptions(): RankValueOptions;
+    /**
+     * An ordered collection of values from {@link RankItem}.
+     * The order of the items is important and must be preserved during processing.
+     */
+    get value(): readonly string[];
+}
+export interface RankDefinition<V extends ValueType = ValueType> extends LeafNodeDefinition<V> {
+    readonly bodyElement: RankControlDefinition;
+}
+export interface RankNode extends BaseValueNode<'string', readonly string[]> {
+    readonly nodeType: 'rank';
+    readonly appearances: UnknownAppearanceDefinition;
+    readonly nodeOptions: null;
+    readonly valueType: 'string';
+    readonly definition: RankDefinition<'string'>;
+    readonly root: RootNode;
+    readonly parent: GeneralParentNode;
+    readonly currentState: RankNodeState;
+    readonly validationState: LeafNodeValidationState;
+    /**
+     * Convenience API to get the {@link RankItem}'s label.
+     */
+    getValueLabel(value: string): TextRange<'item-label'> | null;
+    /**
+     * Set the value which is an ordered collection of values from {@link RankItem}.
+     * Calling this setter replaces the currently value.
+     * If called with an empty array, the current is cleared.
+     */
+    setValues(values: readonly string[]): RootNode;
+}

package/dist/client/RootNode.d.ts

@@ -3,8 +3,8 @@ import { RootDefinition } from '../parse/model/RootDefinition.ts';
 import { BaseNode, BaseNodeState } from './BaseNode.ts';
 import { ActiveLanguage, FormLanguage, FormLanguages } from './FormLanguage.ts';
 import { GeneralChildNode } from './hierarchy.ts';
-import { SubmissionChunkedType, SubmissionOptions } from './submission/SubmissionOptions.ts';
-import { SubmissionResult } from './submission/SubmissionResult.ts';
+import { ChunkedInstancePayload, MonolithicInstancePayload } from './serialization/InstancePayload.ts';
+import { InstancePayloadOptions } from './serialization/InstancePayloadOptions.ts';
 import { AncestorNodeValidationState } from './validation.ts';
 export interface RootNodeState extends BaseNodeState {
     /**
@@ -24,6 +24,7 @@ export interface RootNode extends BaseNode {
      * @todo this along with {@link classes} is... awkward.
      */
     readonly appearances: null;
+    readonly nodeOptions: null;
     /**
      * @todo This is another odd deviation in {@link RootNode}. Unlike
      * {@link languages}, it doesn't feel particularly **essential**. While it
@@ -49,31 +50,37 @@ export interface RootNode extends BaseNode {
     readonly languages: FormLanguages;
     setLanguage(language: FormLanguage): RootNode;
     /**
-     * Prepares the current form instance state for submission.
+     * Prepares the current form instance state as an {@link InstancePayload}.
      *
-     * A {@link SubmissionResult} will be prepared even if the current form state
-     * includes `constraint` or `required` violations. This is intended to serve
-     * two purposes:
+     * A payload will be prepared even if the current form state includes
+     * `constraint` or `required` violations. This supports serveral purposes:
      *
-     * - A client may effectively use this method as a part of its own "submit"
-     *   routine, and use any violations included in the {@link SubmissionResult}
+     * - A client may effectively use this method as a part of its "submit"
+     *   workflow, and use any violations included in the {@link InstancePayload}
      *   to prompt users to address those violations.
      *
-     * - A client may inspect the submission state of a form at any time.
+     * - A client may inspect the serialized instance state of a form at any time.
      *   Depending on the client and use case, this may be a convenience (e.g. for
      *   developers to inspect that form state at a current point in time); or it
      *   may provide necessary functionality (e.g. for test or tooling clients).
      *
-     * Note on asynchrony: preparing a {@link SubmissionResult} is expected to be
-     * a fast operation. It may even be nearly instantaneous, or roughly
+     * - A client may capture _incomplete_ instance state (e.g. for storage in
+     *   client-side storage or similar persistance layer), to resume filling the
+     *   instance at a later time.
+     *
+     * Note on asynchrony: preparing a {@link InstancePayload} is expected to be a
+     * fast operation. It may even be nearly instantaneous, or roughly
      * proportionate to the size of the form itself. However, this method is
      * designed to be asynchronous out of an abundance of caution, anticipating
      * that some as-yet undeveloped operations on binary data (e.g. form
      * attachments) may themselves impose asynchrony (i.e. by interfaces provided
      * by the platform and/or external dependencies).
      *
-     * A client may specify {@link SubmissionOptions<'chunked'>}, in which case a
-     * {@link SubmissionResult<'chunked'>} will be produced, with form attachments
+     * A client may specify {@link InstancePayloadOptions<'chunked'>}, in which
+     * case a {@link ChunkedInstancePayload} will be produced, with form
+     * attachments
      */
-    prepareSubmission<ChunkedType extends SubmissionChunkedType>(options?: SubmissionOptions<ChunkedType>): Promise<SubmissionResult<ChunkedType>>;
+    prepareInstancePayload(): Promise<MonolithicInstancePayload>;
+    prepareInstancePayload(options: InstancePayloadOptions<'monolithic'>): Promise<MonolithicInstancePayload>;
+    prepareInstancePayload(options: InstancePayloadOptions<'chunked'>): Promise<ChunkedInstancePayload>;
 }

package/dist/client/SelectNode.d.ts

@@ -1,20 +1,19 @@
-import { AnySelectDefinition } from '../parse/body/control/select/SelectDefinition.ts';
+import { AnySelectControlDefinition, SelectType } from '../parse/body/control/SelectControlDefinition.ts';
 import { LeafNodeDefinition } from '../parse/model/LeafNodeDefinition.ts';
-import { BaseNode, BaseNodeState } from './BaseNode.ts';
+import { BaseValueNode, BaseValueNodeState } from './BaseValueNode.ts';
 import { NodeAppearances } from './NodeAppearances.ts';
 import { RootNode } from './RootNode.ts';
 import { TextRange } from './TextRange.ts';
+import { ValueType } from './ValueType.ts';
 import { GeneralParentNode } from './hierarchy.ts';
 import { LeafNodeValidationState } from './validation.ts';
 export interface SelectItem {
+    get label(): TextRange<'item-label'>;
     get value(): string;
-    get label(): TextRange<'item-label'> | null;
 }
-export interface SelectNodeState extends BaseNodeState {
+export type SelectValueOptions = readonly SelectItem[];
+export interface SelectNodeState extends BaseValueNodeState<readonly string[]> {
     get children(): null;
-    /**
-     * @todo should {@link BaseNodeState} include this??
-     */
     get valueOptions(): readonly SelectItem[];
     /**
      * This value is treated as set-like by the engine, where each
@@ -28,38 +27,61 @@ export interface SelectNodeState extends BaseNodeState {
      * Should a `SelectNodeState` have this `value` type, whereas a hypothetical
      * `Select1NodeState` would have `get value(): SelectItem | null`?
      */
-    get value(): readonly SelectItem[];
+    get value(): readonly string[];
 }
-export interface SelectDefinition extends LeafNodeDefinition {
-    readonly bodyElement: AnySelectDefinition;
+export interface SelectDefinition<V extends ValueType = ValueType> extends LeafNodeDefinition<V> {
+    readonly bodyElement: AnySelectControlDefinition;
 }
 export type SelectNodeAppearances = NodeAppearances<SelectDefinition>;
-export interface SelectNode extends BaseNode {
+export interface SelectNode extends BaseValueNode<'string', readonly string[]> {
     readonly nodeType: 'select';
+    readonly valueType: 'string';
+    readonly selectType: SelectType;
     readonly appearances: SelectNodeAppearances;
-    readonly definition: SelectDefinition;
+    readonly nodeOptions: null;
+    readonly definition: SelectDefinition<'string'>;
     readonly root: RootNode;
     readonly parent: GeneralParentNode;
     readonly currentState: SelectNodeState;
     readonly validationState: LeafNodeValidationState;
     /**
-     * For use by a client to update the selection of a select node where:
+     * Convenience API to get the {@link SelectItem} which is associated with
+     * {@link value}, if one is currently available—i.e. if it is present in
+     * {@link SelectNodeState.valueOptions}.
+     */
+    getValueOption(value: string): SelectItem | null;
+    /**
+     * Convenience API to determine if {@link value} is currently selected—i.e. if
+     * it is one of the selected values in {@link SelectNodeState.value}.
+     */
+    isSelected(value: string): boolean;
+    /**
+     * Selects a single {@link value}, as provided by a {@link SelectItem.value}.
+     * Calling this setter replaces the currently selected value(s, if any),
+     * where:
      *
-     * - For fields defined with an XForms `<select>`, calling this method is
-     *   additive, i.e. it will include the item in its
-     *   {@link SelectNodeState.value}.
-     * - For fields defined with an XForms `<select1>`, calling this method will
-     *   replace the selection (if any).
+     * - if the provided value is `null`, the current selection is cleared; ELSE
+     * - the provided value is selected in place of any currently selected values.
      *
-     * @todo @see {@link InputNode.setValue} re: write restrictions
-     * @todo @see {@link SelectNodeState.value} re: breaking up the types
+     * This setter is most useful for {@link SelectNode}s associated with an
+     * XForms
+     * {@link https://getodk.github.io/xforms-spec/#body-elements | `<select1>`}
+     * control.
      */
-    select(item: SelectItem): RootNode;
+    selectValue(value: string | null): RootNode;
     /**
-     * For use by a client to remove an item from the node's
-     * {@link SelectNodeState.value}.
+     * Selects any number of {@link values}, as provided by any number of
+     * {@link SelectItem.value}s. Calling this setter replaces the currently
+     * selected value(s, if any). If called with an empty array, the current
+     * selection is cleared.
+     *
+     * This setter is most useful for {@link SelectNode}s associated with an
+     * XForms
+     * {@link https://getodk.github.io/xforms-spec/#body-elements | `<select>`}
+     * control.
      *
-     * @todo @see {@link InputNode.setValue} re: write restrictions
+     * This setter _may_ be used with a `<select1>` control, in which case the
+     * provided {@link values} should produce at most one value.
      */
-    deselect(item: SelectItem): RootNode;
+    selectValues(values: readonly string[]): RootNode;
 }

package/dist/client/SubtreeNode.d.ts

@@ -47,6 +47,7 @@ export interface SubtreeDefinition extends BaseSubtreeDefinition {
 export interface SubtreeNode extends BaseNode {
     readonly nodeType: 'subtree';
     readonly appearances: null;
+    readonly nodeOptions: null;
     readonly definition: SubtreeDefinition;
     readonly root: RootNode;
     readonly parent: GeneralParentNode;

package/dist/client/TriggerNode.d.ts

@@ -1,22 +1,26 @@
+import { TriggerRuntimeValue, TriggerValueType } from '../lib/codecs/TriggerCodec.ts';
 import { UnknownAppearanceDefinition } from '../parse/body/appearance/unknownAppearanceParser.ts';
 import { TriggerControlDefinition } from '../parse/body/control/TriggerControlDefinition.ts';
 import { LeafNodeDefinition } from '../parse/model/LeafNodeDefinition.ts';
-import { BaseNode, BaseNodeState } from './BaseNode.ts';
+import { BaseValueNode, BaseValueNodeState } from './BaseValueNode.ts';
 import { GeneralParentNode } from './hierarchy.ts';
 import { RootNode } from './RootNode.ts';
 import { LeafNodeValidationState } from './validation.ts';
-export interface TriggerNodeState extends BaseNodeState {
+import { ValueType } from './ValueType.ts';
+export type TriggerValue = TriggerRuntimeValue;
+export interface TriggerNodeState extends BaseValueNodeState<TriggerValue> {
     get children(): null;
     get valueOptions(): null;
-    get value(): boolean;
+    get value(): TriggerValue;
 }
-export interface TriggerNodeDefinition extends LeafNodeDefinition {
+export interface TriggerNodeDefinition<V extends ValueType = ValueType> extends LeafNodeDefinition<V> {
     readonly bodyElement: TriggerControlDefinition;
 }
-export interface TriggerNode extends BaseNode {
+export interface TriggerNode extends BaseValueNode<TriggerValueType, TriggerValue> {
     readonly nodeType: 'trigger';
-    readonly definition: TriggerNodeDefinition;
+    readonly definition: TriggerNodeDefinition<TriggerValueType>;
     readonly appearances: UnknownAppearanceDefinition;
+    readonly nodeOptions: null;
     readonly root: RootNode;
     readonly parent: GeneralParentNode;
     readonly currentState: TriggerNodeState;

package/dist/client/constants.d.ts

@@ -1,17 +1,16 @@
 import { ValidationTextRole } from './TextRange.ts';
 export declare const MISSING_RESOURCE_BEHAVIOR: {
     /**
-     * When this behavior is configured, {@link InitializeForm | initializing} a
-     * {@link PrimaryInstance} for a form which references any **missing**
-     * resources will fail, producing an error to the calling client.
+     * When this behavior is configured, {@link LoadForm | loading a form} which
+     * references any **missing** resources will fail, producing an error to the
+     * calling client.
      *
      * @see {@link MissingResourceBehavior}
      */
     readonly ERROR: "ERROR";
     /**
-     * When this behavior is configured, {@link InitializeForm | initializing} a
-     * {@link PrimaryInstance} for a form which references any **missing**
-     * resources will succeed (producing a warning).
+     * When this behavior is configured, {@link LoadForm | loading a form} which
+     * references any **missing** resources will succeed (producing a warning).
      *
      * Such missing resources will be parsed as if they are blank, as appropriate
      * for the resource's XForm semantic usage and/or format.
@@ -28,8 +27,8 @@ export type MissingResourceBehaviorError = typeof MISSING_RESOURCE_BEHAVIOR.ERRO
 export type MissingResourceBehaviorBlank = typeof MISSING_RESOURCE_BEHAVIOR.BLANK;
 export type MissingResourceBehaviorDefault = typeof MISSING_RESOURCE_BEHAVIOR.DEFAULT;
 /**
- * Specifies behavior for {@link InitializeForm | initializing} a form's
- * {@link PrimaryInstance} which references any **missing** resources.
+ * Specifies behavior for {@link LoadForm | loading a form} which references any
+ * **missing** resources.
  *
  * Here the term "missing" is consistent with
  * {@link https://www.rfc-editor.org/rfc/rfc9110#status.404 | HTTP 404 status}
@@ -51,8 +50,8 @@ export declare const VALIDATION_TEXT: {
 };
 type ValidationTextDefaults = typeof VALIDATION_TEXT;
 export type ValidationTextDefault<Role extends ValidationTextRole> = ValidationTextDefaults[Role];
-export declare const SUBMISSION_INSTANCE_FILE_NAME = "xml_submission_file";
-export type SubmissionInstanceFileName = typeof SUBMISSION_INSTANCE_FILE_NAME;
-export declare const SUBMISSION_INSTANCE_FILE_TYPE = "text/xml";
-export type SubmissionInstanceFileType = typeof SUBMISSION_INSTANCE_FILE_TYPE;
+export declare const INSTANCE_FILE_NAME = "xml_submission_file";
+export type INSTANCE_FILE_NAME = typeof INSTANCE_FILE_NAME;
+export declare const INSTANCE_FILE_TYPE = "text/xml";
+export type INSTANCE_FILE_TYPE = typeof INSTANCE_FILE_TYPE;
 export {};

package/dist/client/form/CreateFormInstance.d.ts

@@ -0,0 +1,14 @@
+import { FormInstance, FormInstanceCreateMode } from './FormInstance.ts';
+import { FormInstanceConfig } from './FormInstanceConfig.ts';
+export type CreatedFormInstance = FormInstance<FormInstanceCreateMode>;
+/**
+ * @todo This is fallible! Client-facing interfaces will need to account for
+ * this. We've begun addressing fallibility _at the interface level_ in
+ * {@link LoadForm} (with {@link LoadFormResult}). We'll eventually have a more
+ * general interface pattern for this, and we'll apply it here as well. The baby
+ * step approach in {@link LoadFormResult} is impractical here due to
+ * engine-internal designs, and revising that is currently out of scope. As
+ * such, explicit interface-level documentation of fallibility is deferred here,
+ * on {@link RootNode} itself, and into any of its sub-interfaces.
+ */
+export type CreateFormInstance = (config?: FormInstanceConfig) => CreatedFormInstance;