@getodk/xforms-engine 0.4.0 → 0.6.0

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 StringNode.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 StringNode.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/ValueType.d.ts

@@ -0,0 +1,3 @@
+import { ExpandUnion } from '../../../common/types/helpers.js';
+import { BindType } from '../parse/model/BindTypeDefinition.ts';
+export type ValueType = ExpandUnion<BindType>;

package/dist/client/constants.d.ts

@@ -1,8 +1,58 @@
 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.
+     *
+     * @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).
+     *
+     * Such missing resources will be parsed as if they are blank, as appropriate
+     * for the resource's XForm semantic usage and/or format.
+     *
+     * @see {@link MissingResourceBehavior}
+     */
+    readonly BLANK: "BLANK";
+    /**
+     * @see {@link MISSING_RESOURCE_BEHAVIOR.ERROR}
+     */
+    readonly DEFAULT: "ERROR";
+};
+export type MissingResourceBehaviorError = typeof MISSING_RESOURCE_BEHAVIOR.ERROR;
+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.
+ *
+ * Here the term "missing" is consistent with
+ * {@link https://www.rfc-editor.org/rfc/rfc9110#status.404 | HTTP 404 status}
+ * semantics. Clients which provide access to form attachments by performing
+ * HTTP network requests (e.g. with {@link fetch}) can generally convey this
+ * semantic meaning with a standard {@link Response}.
+ *
+ * **IMPORTANT**
+ *
+ * The term "missing" is distinct from other network/IO failures, e.g. when
+ * network access itself is unavailable. In these cases, the engine will
+ * consider a resource's availability **ambiguous**, producing an error
+ * regardless of the configured behavior for **missing** resources.
+ */
+export type MissingResourceBehavior = MissingResourceBehaviorError | MissingResourceBehaviorBlank;
 export declare const VALIDATION_TEXT: {
     readonly constraintMsg: "Condition not satisfied: constraint";
     readonly requiredMsg: "Condition not satisfied: required";
 };
 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 {};

package/dist/client/hierarchy.d.ts

@@ -1,21 +1,21 @@
 import { ExpandUnion } from '../../../common/types/helpers.d.ts';
 import { GroupNode } from './GroupNode.ts';
-import { ModelValueNode } from './ModelValueNode.ts';
-import { NoteNode } from './NoteNode.ts';
+import { AnyInputNode } from './InputNode.ts';
+import { AnyModelValueNode } from './ModelValueNode.ts';
+import { AnyNoteNode } from './NoteNode.ts';
+import { AnyRangeNode } from './RangeNode.ts';
 import { RepeatInstanceNode } from './repeat/RepeatInstanceNode.ts';
 import { RepeatRangeControlledNode } from './repeat/RepeatRangeControlledNode.ts';
 import { RepeatRangeUncontrolledNode } from './repeat/RepeatRangeUncontrolledNode.ts';
 import { RootNode } from './RootNode.ts';
 import { SelectNode } from './SelectNode.ts';
-import { StringNode } from './StringNode.ts';
 import { SubtreeNode } from './SubtreeNode.ts';
 import { TriggerNode } from './TriggerNode.ts';
-import { RangeNode } from './unsupported/RangeNode.ts';
-import { RankNode } from './unsupported/RankNode.ts';
+import { RankNode } from './RankNode.ts';
 import { UploadNode } from './unsupported/UploadNode.ts';
-export type AnyUnsupportedControlNode = RangeNode | RankNode | UploadNode;
-export type AnyControlNode = NoteNode | SelectNode | StringNode | TriggerNode;
-export type AnyLeafNode = AnyControlNode | AnyUnsupportedControlNode | ModelValueNode;
+export type AnyUnsupportedControlNode = UploadNode;
+export type AnyControlNode = AnyInputNode | AnyNoteNode | AnyRangeNode | RankNode | SelectNode | TriggerNode;
+export type AnyLeafNode = AnyControlNode | AnyModelValueNode | AnyUnsupportedControlNode;
 export type RepeatRangeNode = RepeatRangeControlledNode | RepeatRangeUncontrolledNode;
 /**
  * Any of the concrete node types which may be a parent of non-repeat instance

package/dist/client/identity.d.ts

@@ -0,0 +1,14 @@
+type ODKXFormsUUID = `uuid:${string}`;
+/**
+ * @see {@link https://getodk.github.io/xforms-spec/#metadata}
+ */
+export type InstanceID = ODKXFormsUUID;
+/**
+ * @see {@link https://getodk.github.io/xforms-spec/#metadata}
+ */
+export type DeprecatedID = ODKXFormsUUID;
+/**
+ * Represents a session-stable identifier for any particular node i
+ */
+export type FormNodeID = `node:${string}`;
+export {};

package/dist/client/node-types.d.ts

@@ -1,3 +1,4 @@
-export type UnsupportedControlNodeType = 'range' | 'rank' | 'upload';
+export type UnsupportedControlNodeType = 'rank' | 'upload';
 export type RepeatRangeNodeType = 'repeat-range:controlled' | 'repeat-range:uncontrolled';
-export type InstanceNodeType = 'root' | RepeatRangeNodeType | 'repeat-instance' | 'group' | 'subtree' | 'model-value' | 'note' | 'select' | 'string' | 'trigger' | UnsupportedControlNodeType;
+export type LeafNodeType = 'model-value' | 'note' | 'select' | 'input' | 'trigger' | 'range' | UnsupportedControlNodeType;
+export type InstanceNodeType = 'root' | RepeatRangeNodeType | 'repeat-instance' | 'group' | 'subtree' | LeafNodeType | UnsupportedControlNodeType;

package/dist/client/resources.d.ts

@@ -0,0 +1,93 @@
+import { JRResourceURL } from '../../../common/src/jr-resources/JRResourceURL.ts';
+interface FetchResourceHeadersIterator<T> extends IteratorObject<T, BuiltinIteratorReturn, unknown> {
+    [Symbol.iterator](): FetchResourceHeadersIterator<T>;
+}
+type FetchResourceHeadersForEachCallbackFn = (value: string, key: string, parent: FetchResourceResponseHeaders) => void;
+/**
+ * A read-only strict subset of the web standard {@link Headers}.
+ *
+ * Note that the engine may make the following assumptions about
+ * {@link FetchResourceResponse.headers}:
+ *
+ * - If {@link FetchResourceResponse} is an instance of {@link Response}, it
+ *   will be assumed its {@link FetchResourceResponse.headers | headers object}
+ *   _is present_, and that it is an instance of {@link Headers}. In other
+ *   words: for the purposes of resource resolution, we explicitly expect that
+ *   clients using APIs provided by the runtime platform (or polyfills thereof)
+ *   will not monkey-patch properties of values produced by those APIs.
+ *
+ * - If the object is an instance of {@link Headers} (whether by inference as a
+ *   property of {@link Response}, or by a direct instance type check), the
+ *   engine will assume it is safe to treat header names as case insensitive for
+ *   any lookups it may perform. In other words: we explicitly expect that
+ *   clients _providing access_ to APIs rovided by the runtime platform (or
+ *   polyfills thereof) will not alter the guarantees of those APIs.
+ *
+ * - If the object is not an instance of {@link Headers}, it will be treated as
+ *   a {@link ReadonlyMap<string, string>}. In other words: we explicitly expect
+ *   that clients, when providing a bespoke implementation of
+ *   {@link FetchResourceResponse} and its constituent parts, will likely
+ *   implement them partially (and in the case of
+ *   {@link FetchResourceResponse.headers}, with the nearest common idiom
+ *   available). In this case, we will favor a best effort at correctness,
+ *   generally at some expense of performance.
+ */
+export interface FetchResourceResponseHeaders {
+    [Symbol.iterator](): FetchResourceHeadersIterator<[string, string]>;
+    entries(): FetchResourceHeadersIterator<[string, string]>;
+    keys(): FetchResourceHeadersIterator<string>;
+    values(): FetchResourceHeadersIterator<string>;
+    get(name: string): string | null;
+    has(name: string): boolean;
+    forEach(callbackfn: FetchResourceHeadersForEachCallbackFn): void;
+}
+/**
+ * This is a strict subset of the web standard {@link Response}. Clients are
+ * encouraged to use the global {@link Response} constructor (as provided by the
+ * runtime platform, or by a global runtime polyfill), but may also provide a
+ * bespoke implementation if it suits their needs.
+ *
+ * Since we cannot assume a client's implementation will always be an instance
+ * of {@link Response}, we make some assumptions about its {@link headers}
+ * object (if available, as detailed on {@link FetchResourceResponseHeaders}).
+ *
+ * For other properties, we make the following assumptions (all of which are
+ * assumptions we would make about a platform-provided/polyfilled
+ * {@link Response}, but are explicitly stated for the benefit of confidence in
+ * client implementations):
+ *
+ * - If we read {@link body} directly, we will assume it is consumed on first
+ *   read, and will not read it again.
+ *
+ * - We assume that {@link blob} and {@link text} indirectly consume
+ *   {@link body} on first read as well, and will only ever read one of each of
+ *   these properties, and only ever once.
+ *
+ * Furthermore, if the engine intends to read {@link body} (or its indirect
+ * {@link blob} or {@link text} consumers), it will do so in the course of a
+ * client's call to {@link initializeForm}, and before the
+ * {@link Promise<PrimaryInstance>} returned by that call is resolved.
+ */
+export interface FetchResourceResponse {
+    readonly ok?: boolean;
+    readonly status?: number;
+    readonly body?: ReadableStream<Uint8Array> | null;
+    readonly bodyUsed?: boolean;
+    readonly headers?: FetchResourceResponseHeaders;
+    readonly blob: () => Promise<Blob>;
+    readonly text: () => Promise<string>;
+}
+/**
+ * This is a strict subset of the web standard `fetch` interface. It implicitly
+ * assumes that the engine itself will only ever perform `GET`-like network/IO
+ * 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 for the engine to include `Accept`
+ * headers in resource requests issued to a client's {@link FetchResource}
+ * implementation).
+ */
+export type FetchResource<Resource extends URL = URL> = (resource: Resource) => Promise<FetchResourceResponse>;
+export type FormAttachmentURL = JRResourceURL;
+export type FetchFormAttachment = FetchResource<FormAttachmentURL>;
+export {};

package/dist/client/submission/SubmissionData.d.ts

@@ -0,0 +1,7 @@
+import { SubmissionInstanceFile, SubmissionInstanceFileName } from './SubmissionInstanceFile.ts';
+export interface SubmissionData extends FormData {
+    get(name: SubmissionInstanceFileName): SubmissionInstanceFile;
+    get(name: string): FormDataEntryValue | null;
+    has(name: SubmissionInstanceFileName): true;
+    has(name: string): boolean;
+}

package/dist/client/submission/SubmissionDefinition.d.ts

@@ -0,0 +1,14 @@
+export interface SubmissionDefinition {
+    /**
+     * @see {@link https://getodk.github.io/xforms-spec/#submission-attributes | `action` submission attribute}
+     */
+    readonly submissionAction: URL | null;
+    /**
+     * @see {@link https://getodk.github.io/xforms-spec/#submission-attributes | `method` submission attribute}
+     */
+    readonly submissionMethod: 'post';
+    /**
+     * @see {@link https://getodk.github.io/xforms-spec/#submission-attributes | `base64RsaPublicKey` submission attribute}
+     */
+    readonly encryptionKey: string | null;
+}

package/dist/client/submission/SubmissionInstanceFile.d.ts

@@ -0,0 +1,6 @@
+import { SubmissionInstanceFileName, SubmissionInstanceFileType } from '../constants.ts';
+export type { SubmissionInstanceFileName, SubmissionInstanceFileType };
+export interface SubmissionInstanceFile extends File {
+    readonly name: SubmissionInstanceFileName;
+    readonly type: SubmissionInstanceFileType;
+}

package/dist/client/submission/SubmissionOptions.d.ts

@@ -0,0 +1,23 @@
+export type SubmissionChunkedType = 'chunked' | 'monolithic';
+interface BaseSubmissionOptions<ChunkedType extends SubmissionChunkedType> {
+    readonly chunked?: ChunkedType | undefined;
+    /**
+     * As described in the
+     * {@link https://docs.getodk.org/openrosa-form-submission/#extended-transmission-considerations | OpenRosa Form Submission API},
+     * clients may obtain this value from an OpenRosa server's
+     * `X-OpenRosa-Accept-Content-Length` header.
+     */
+    readonly maxSize?: number;
+}
+interface ChunkedSubmissionOptions extends BaseSubmissionOptions<'chunked'> {
+    readonly maxSize: number;
+}
+interface MonolithicSubmissionOptions extends BaseSubmissionOptions<'monolithic'> {
+    readonly chunked?: 'monolithic' | undefined;
+    readonly maxSize?: never;
+}
+export type SubmissionOptions<ChunkedType extends SubmissionChunkedType = 'monolithic'> = {
+    chunked: ChunkedSubmissionOptions;
+    monolithic: MonolithicSubmissionOptions;
+}[ChunkedType];
+export {};

package/dist/client/submission/SubmissionResult.d.ts

@@ -0,0 +1,91 @@
+import { DescendantNodeViolationReference } from '../validation.ts';
+import { SubmissionData } from './SubmissionData.ts';
+import { SubmissionDefinition } from './SubmissionDefinition.ts';
+import { SubmissionChunkedType } from './SubmissionOptions.ts';
+export type SubmissionResultStatus = 'pending' | 'max-size-exceeded' | 'ready';
+type SubmissionResultData<ChunkedType extends SubmissionChunkedType> = {
+    chunked: readonly [SubmissionData, ...SubmissionData[]];
+    monolithic: SubmissionData;
+}[ChunkedType];
+/**
+ * Provides detail about an individual submission attachment {@link File}s which
+ * exceeds the client-specified {@link maxSize} for a
+ * {@link SubmissionResult<'chunked'> | chunked submission result}. Clients may
+ * use this value to provide guidance to users.
+ *
+ * @todo We may want to consider (a) making {@link maxSize} a configuration the
+ * client can provide when initializing a form instance, rather than only on
+ * submission; and then (b) treating a maximum size violation as another kind of
+ * node-level violation. This would go beyond the kinds of validation specified
+ * by ODK XForms, but it would make a lot of _conceptual sense_.
+ *
+ * It would almost certainly be helpful to alert users to violations as the
+ * occur, rather than only at submission time (where they have likely already
+ * moved on). This is something clients can do without engine support, but it
+ * would likely promote good usability patterns if the engine makes it an
+ * obvious and uniform option at the main engine/client entrypoint.
+ *
+ * @todo If we consider the above, we'd want to reframe _this interface_ to
+ * match the shape of other {@link AnyViolation | violations} (adding it as a
+ * member of that union). We'd also likely eliminate
+ * {@link MaxSizeExceededResult} in the process, since
+ * {@link PendingSubmissionResult} would then cover the case.
+ */
+interface MaxSizeViolation {
+    /**
+     * Specifies the index of
+     * {@link SubmissionResultData<'chunked'> | chunked submission data} where a
+     * submission attachment {@link File} exceeds the client-specified
+     * {@link maxSize}.
+     */
+    readonly dataIndex: number;
+    /**
+     * Specifies the name of the file which exceeds the client-specified
+     * {@link maxSize}. This name can also be used as a key to access the
+     * violating {@link File}/submission attachment, in the {@link SubmissionData}
+     * at the specified {@link dataIndex}.
+     */
+    readonly fileName: string;
+    /**
+     * Reflects the client-specified maximum size for each chunk of a
+     * {@link SubmissionResult<'chunked'> | chunked submission result}.
+     */
+    readonly maxSize: number;
+    /**
+     * Details the actual size of the violating {@link File}/submission
+     * attachment. Along with {@link maxSize}. Clients may use the delta between
+     * this value and {@link maxSize} to provide detailed guidance to users.
+     */
+    readonly actualSize: number;
+}
+type SubmissionResultViolation = DescendantNodeViolationReference | MaxSizeViolation;
+interface BaseSubmissionResult<ChunkedType extends SubmissionChunkedType> {
+    readonly status: SubmissionResultStatus;
+    readonly definition: SubmissionDefinition;
+    get violations(): readonly SubmissionResultViolation[] | null;
+    /**
+     * Submission data may be chunked according to the
+     * {@link SubmissionOptions.maxSize | maxSize submission option}
+     */
+    readonly data: SubmissionResultData<ChunkedType>;
+}
+interface PendingSubmissionResult<ChunkedType extends SubmissionChunkedType> extends BaseSubmissionResult<ChunkedType> {
+    readonly status: 'pending';
+    get violations(): readonly DescendantNodeViolationReference[];
+}
+interface MaxSizeExceededResult extends BaseSubmissionResult<'chunked'> {
+    readonly status: 'max-size-exceeded';
+    get violations(): readonly MaxSizeViolation[];
+}
+interface ReadySubmissionResult<ChunkedType extends SubmissionChunkedType> extends BaseSubmissionResult<ChunkedType> {
+    readonly status: 'ready';
+    get violations(): null;
+}
+type CommonSubmissionResult<ChunkedType extends SubmissionChunkedType> = PendingSubmissionResult<ChunkedType> | ReadySubmissionResult<ChunkedType>;
+export type ChunkedSubmissionResult = CommonSubmissionResult<'chunked'> | MaxSizeExceededResult;
+export type MonolithicSubmissionResult = CommonSubmissionResult<'monolithic'>;
+export type SubmissionResult<ChunkedType extends SubmissionChunkedType> = {
+    chunked: ChunkedSubmissionResult;
+    monolithic: MonolithicSubmissionResult;
+}[ChunkedType];
+export {};

package/dist/client/submission/SubmissionState.d.ts

@@ -0,0 +1,12 @@
+export interface SubmissionState {
+    /**
+     * Represents the serialized XML state of a given node, as it will be prepared
+     * for submission. The value produced in {@link RootNode.submissionState} is
+     * the same serialization which will be produced for the complete submission.
+     *
+     * @todo Note that this particular aspect of the design doesn't yet address
+     * production of unique file names. As such, this may change as we introduce
+     * affected data types (and their supporting nodes).
+     */
+    get submissionXML(): string;
+}

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

@@ -1,6 +1,4 @@
 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';
@@ -13,7 +11,7 @@ export interface UnsupportedControlNodeState extends BaseNodeState {
     get valueOptions(): unknown;
     get value(): unknown;
 }
-export type UnsupportedControlElementDefinition = RangeControlDefinition | RankControlDefinition | UploadControlDefinition;
+export type UnsupportedControlElementDefinition = UploadControlDefinition;
 export interface UnsupportedControlDefinition extends LeafNodeDefinition {
     readonly bodyElement: UnsupportedControlElementDefinition;
 }

package/dist/client/validation.d.ts

@@ -1,4 +1,4 @@
-import { NodeID } from '../instance/identity.ts';
+import { FormNodeID } from './identity.ts';
 import { TextRange } from './TextRange.ts';
 interface BaseValidity {
     /**
@@ -144,7 +144,7 @@ export interface LeafNodeValidationState {
  * each property will be directly computed from the affected node.
  */
 export interface DescendantNodeViolationReference {
-    readonly nodeId: NodeID;
+    readonly nodeId: FormNodeID;
     get reference(): string;
     get violation(): AnyViolation;
 }

package/dist/error/ErrorProductionDesignPendingError.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Temporary representation of newly introduced error conditions which we may
+ * produce to clients (and beyond). Intentionally a stub pending a more concrete
+ * design and implementation of our approach to producing Result types.
+ */
+export declare class ErrorProductionDesignPendingError extends Error {
+}

package/dist/error/RankMissingValueError.d.ts

@@ -0,0 +1,3 @@
+export declare class RankMissingValueError extends Error {
+    constructor(message: string);
+}

package/dist/error/RankValueTypeError.d.ts

@@ -0,0 +1,6 @@
+import { XFormsSpecViolationError } from './XFormsSpecViolationError.ts';
+import { RankDefinition } from '../client/RankNode.ts';
+import { UnsupportedBaseItemValueType } from '../lib/codecs/items/BaseItemCodec.ts';
+export declare class RankValueTypeError extends XFormsSpecViolationError {
+    constructor(definition: RankDefinition<UnsupportedBaseItemValueType>);
+}

package/dist/error/SelectValueTypeError.d.ts

@@ -0,0 +1,15 @@
+import { SelectDefinition } from '../client/SelectNode.ts';
+import { UnsupportedBaseItemValueType } from '../lib/codecs/items/BaseItemCodec.ts';
+import { XFormsSpecViolationError } from './XFormsSpecViolationError.ts';
+/**
+ * @todo It would be good to have a standardized way to use specific types of
+ * errors as a prompt for feedback. There is currently a feedback link presented
+ * by `@getodk/web-forms`, which is conditionally displayed (condition is
+ * evidently controlled by a
+ * {@link https://vuejs.org/api/sfc-script-setup#defineoptions | Vue component option}).
+ *
+ * @see {@link https://github.com/getodk/web-forms/issues/276}
+ */
+export declare class SelectValueTypeError extends XFormsSpecViolationError {
+    constructor(definition: SelectDefinition<UnsupportedBaseItemValueType>);
+}

package/dist/error/ValueTypeInvariantError.d.ts

@@ -0,0 +1,17 @@
+import { ValueType } from '../client/ValueType.ts';
+import { ErrorProductionDesignPendingError } from './ErrorProductionDesignPendingError.ts';
+/**
+ * Temporary(?) representation of error conditions arising from violation of
+ * invariants specific to {@link valueType}.
+ *
+ * @todo The intent of this distinct subclass of
+ * {@link ErrorProductionDesignPendingError} is to call out cases where we may
+ * want to represent such errors to clients as **validation errors** in the
+ * future. We identified this as probably desirable in the initial work on `int`
+ * and `decimal` value types, but held off on that aspect of implementation to
+ * tame scope.
+ */
+export declare class ValueTypeInvariantError extends ErrorProductionDesignPendingError {
+    readonly valueType: ValueType;
+    constructor(valueType: ValueType, message: string);
+}

package/dist/error/XFormsSpecViolationError.d.ts

@@ -0,0 +1,2 @@
+export declare abstract class XFormsSpecViolationError extends Error {
+}

package/dist/error/XPathFunctionalityError.d.ts

@@ -0,0 +1,14 @@
+import { AnyFunction, ExpandUnion } from '../../../common/types/helpers.js';
+import { XPathDOMAdapter, XPathNode } from '@getodk/xpath';
+/**
+ * @todo this is general enough to go in `@getodk/common`. Holding off until
+ * it's clear we actually benefit from this particular type gymnastic.
+ */
+type MethodNameOf<T> = {
+    [K in keyof T]: T[K] extends AnyFunction ? K : never;
+}[keyof T];
+export type XPathFunctionalityErrorCategory = ExpandUnion<MethodNameOf<XPathDOMAdapter<XPathNode>> | 'processing-instruction'>;
+export declare abstract class XPathFunctionalityError extends Error {
+    constructor(functionalityMessagePrefix: string, category: XPathFunctionalityErrorCategory);
+}
+export {};