@getodk/xforms-engine 0.5.0 → 0.7.0

package/dist/lib/names/NamespaceDeclarationMap.d.ts

@@ -0,0 +1,137 @@
+import { NamespaceDeclaration } from './NamespaceDeclaration.ts';
+import { NamespaceURI, QualifiedName } from './QualifiedName.ts';
+export interface NamedNodeDefinition {
+    readonly qualifiedName: QualifiedName;
+}
+type NamedNodeDefinitionMap = ReadonlyMap<QualifiedName, NamedNodeDefinition>;
+export interface NamedSubtreeDefinition extends NamedNodeDefinition {
+    readonly namespaceDeclarations: NamespaceDeclarationMap;
+    readonly parent: NamedSubtreeDefinition | null;
+    readonly attributes?: NamedNodeDefinitionMap;
+}
+/**
+ * @todo This is a bit of a code style experiment! Responsive to
+ * {@link https://github.com/getodk/web-forms/issues/296 | How should we represent enumerated types?}.
+ * Observations to be considered for that issue...
+ *
+ * This more or less works as one would expect, with one really irritating
+ * downside: unlike a **TypeScript `enum`**, code completions (in VSCode, but
+ * I'd expect the same for any TypeScript language server/LSP implementation)
+ * automatically suggest the bare string values rather than the equivalent
+ * syntax referencing the enumerations as defined here. Without care, it would
+ * be fairly trivial to lose consistency between the source "enum" and consuming
+ * code which we presume to be an exhaustive check (such as the `switch`
+ * statement operating on it below). This is somewhat mitigated for now by
+ * habitual use of {@link UnreachableError} (and would be better mitigated by a
+ * lint rule to enforce exhaustiveness checks over similar enumerations). But
+ * there is an obvious _stylistic mismatch_ between how an editor treats "thing
+ * shaped like `enum` but not semantically an `enum`", whereas there's no such
+ * mismatch in how it treats a plain "union of strings". If nothing else, that
+ * mismatch would tend to exacerbate exhaustiveness drift as an enumeration
+ * evolves.
+ */
+declare const DECLARE_NAMESPACE_RESULTS: {
+    readonly SUCCESS: "SUCCESS";
+    readonly HOISTED: "HOISTED";
+    readonly DEFERRED: "DEFERRED";
+    readonly REDUNDANT: "REDUNDANT";
+    readonly CONFLICT: "CONFLICT";
+};
+type DeclareNamespaceResultEnum = typeof DECLARE_NAMESPACE_RESULTS;
+type DeclareNamespaceResult = DeclareNamespaceResultEnum[keyof DeclareNamespaceResultEnum];
+export declare class NamespaceDeclarationMap extends Map<string | null, NamespaceDeclaration> {
+    readonly subtree: NamedSubtreeDefinition;
+    constructor(subtree: NamedSubtreeDefinition);
+    /**
+     * For any {@link definition | named node definition}, we can _infer_ a
+     * namespace declaration (rather than parsing it directly, which is error
+     * prone depending on parsing context) from that definition's
+     * {@link QualifiedName.namespaceURI} and {@link QualifiedName.prefix} (if the
+     * latter is defined).
+     *
+     * If a namespace declaration can be inferred, we "declare" (set, in
+     * {@link Map} semantics) it in **EITHER**:
+     *
+     * - An ancestor {@link NamedSubtreeDefinition | named subtree definition}'s
+     *   {@link NamespaceDeclarationMap}: if such an ancestor exists and has no
+     *   conflicting declaration for the same prefix; **OR**
+     * - This {@link NamespaceDeclarationMap}, if no suitable ancestor exists
+     *
+     * This can be described as "hoisting" the declaration to the uppermost node
+     * (or definitional representation of same) where it would be valid to declare
+     * the namespace for its prefix.
+     *
+     * In the following example, note that this logic applies for arbitrary tree
+     * structures satisfying the {@link NamedNodeDefinition} and
+     * {@link NamedSubtreeDefinition} interfaces. XML syntax is used to provide a
+     * concise explanation, but it should not be inferred that this is operating
+     * directly on an XML value (or any platform-native DOM structure of the
+     * same).
+     *
+     * @example Given an input tree like:
+     *
+     * ```xml
+     * <foo xmlns="https://example.com/DEFAULT_ONE">
+     *   <bar:bat xmlns:bar="https://example.com/bar"/>
+     *   <baz xmlns="https://example.com/DEFAULT_TWO"/>
+     * </foo>
+     * ```
+     *
+     * The namespace declarations will be assigned as if they'd been declared
+     * like:
+     *
+     * ```xml
+     * <foo
+     *   xmlns="https://example.com/DEFAULT_ONE"
+     *   xmlns:bar="https://example.com/bar"
+     * >
+     *   <!-- bar declaration has no conflict in foo, hoisted to parent -->
+     *   <bar:bat/>
+     *   <!-- default declaration conflicts with foo's default, not hoisted -->
+     *   <baz xmlns="https://example.com/DEFAULT_TWO"/>
+     * </foo>
+     * ```
+     *
+     * **IMPORTANT:** this behavior may seem overly complicated! It should be
+     * noted that the behavior:
+     *
+     * 1. ... is conceptually similar to behavior observable in a web standard
+     *    WHAT Working Group DOM (as in browser DOM, XML DOM) implementation.
+     *    There, serializing any subtree element will produce namespace
+     *    declarations on the root element for any namespaces _referenced within
+     *    its subtree but declared on an ancestor_. Note that in this case, the
+     *    hierarchical behavior is inverted, but it demonstrates the same
+     *    effective namespace scoping semantics.
+     *
+     * 2. ... vastly simplifies our ability to produce a compact XML
+     *    representation from any arbitrary tree representation of its nodes.
+     *    Hoisting namespace declarations to their uppermost scope, and
+     *    deduplicating recursively up the ancestor tree, ensures that we only
+     *    declare a given namespace once as it is referenced.
+     *
+     * @todo While this design is intended to help with producing compact
+     * serialized XML, at time of writing there is still an aspect which is
+     * unaddressed in the serialization logic: we assume namespace declarations
+     * are referenced if they've been parsed. This logic doesn't hold for nodes
+     * which are ultimately omitted from serialization, which would occur for
+     * non-relevant nodes, and repeat ranges with zero repeat instances (or any of
+     * their descendants). A future iteration of this same behavior could produce
+     * XML which is theoretically more compact, by performing the same declaration
+     * hoisting logic _dynamically at call time_ rather than at parse time.
+     */
+    declareNamespace(definition: NamedNodeDefinition): DeclareNamespaceResult;
+    /**
+     * Given a {@link namespaceURI}, resolves a declared prefix (which may be
+     * `null`) for the {@link subtree} context **or any of its ancestors**. This
+     * is an important semantic detail:
+     *
+     * - Namespace declarations on a given subtree are effective for all of its
+     *   descendants _until another declaration for the same prefix or namespace
+     *   URI is encountered_
+     * - We "hoist" namespace declarations up to the uppermost {@link subtree}'s
+     *   {@link NamespaceDeclarationMap} during parsing (as described in more
+     *   detail on {@link declareNamespace}).
+     */
+    lookupPrefix(namespaceURI: NamespaceURI): string | null;
+}
+export {};

package/dist/lib/names/NamespaceURL.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Convenience wrapper to represent an XML namespace URI as a {@link URL}. This
+ * representation is used/responsible for:
+ *
+ * - normalized logic for XML semantics around special namespace URI values, in
+ *   particular for consistent handling of the "null namespace" (input for such
+ *   is accepted as either an empty string or `null`)
+ * - validation of input: a non-"null namespace" value will be rejected if it is
+ *   not a valid URI string
+ * - type-level distinction between a namespace URI and a
+ *   {@link NamespaceDeclaration.declaredPrefix | namespace declaration's prefix},
+ *   as an aide to avoid using one in place of the other as e.g. a positional
+ *   argument
+ *
+ * @todo Test the finer distinctions between "URL" and "URI"!
+ *
+ * @todo Probably not a huge deal in the scheme of things, but this is almost
+ * entirely pure overhead at runtime! The "validation" use case is kind of a
+ * stretch, and may well be wrong. The type-level distinction from a namespace
+ * prefix, however, has proved useful **quite a few times** during iteration of
+ * this change. If we can actually measure an impact, it might be worth instead
+ * considering "branded types" for the type-level distinct (in which case we
+ * could use a factory function to handle both the branding and special XML
+ * semantics).
+ */
+export declare class NamespaceURL extends URL {
+    static from(namespaceURI: NamespaceURL | string | null): NamespaceURL | null;
+    readonly href: string;
+    private constructor();
+}

package/dist/lib/names/QualifiedName.d.ts

@@ -0,0 +1,113 @@
+import { NamespaceURL } from './NamespaceURL.ts';
+export type NamespaceURI = NamespaceURL | null;
+export type QualifiedNamePrefix = string | null;
+export interface NamespaceQualifiedNameSource {
+    readonly namespaceURI: NamespaceURI | string;
+    readonly localName: string;
+    /**
+     * Note that this property is intentionally optional as one of the
+     * {@link QualifiedNameSource | QualifiedName source input}, and its absence
+     * is treated differently from an explicitly assigned `null` value.
+     *
+     * @see {@link SourcePrefixUnspecified}, {@link DeferredPrefix}
+     */
+    readonly prefix?: QualifiedNamePrefix;
+}
+declare const SOURCE_PREFIX_UNSPECIFIED: unique symbol;
+/**
+ * May be used as a placeholder for a {@link QualifiedName.prefix}, where the
+ * actual prefix may not be known at definition time.
+ *
+ * Example: parsing non-XML sources into an XML-like tree, e.g. for XPath
+ * evaluation; in which case, we may not need to resolve a prefix for the name
+ * until such a node is serialized as XML, if it ever is.
+ */
+type SourcePrefixUnspecified = typeof SOURCE_PREFIX_UNSPECIFIED;
+/**
+ * Represents a {@link QualifiedName.prefix} whose resolution may be deferred,
+ * e.g. until all requisite parsing is complete and/or until XML serialization
+ * requires use of a prefix to represent the corresponding
+ * {@link QualifiedName.namespaceURI}.
+ */
+type DeferredPrefix = string | null | SourcePrefixUnspecified;
+interface DeferredPrefixedQualifiedNameSource {
+    readonly namespaceURI: NamespaceURI | string;
+    readonly prefix: DeferredPrefix;
+    readonly localName: string;
+}
+export type QualifiedNameSource = NamespaceQualifiedNameSource | DeferredPrefixedQualifiedNameSource;
+interface PrefixResolutionOptions {
+    lookupPrefix(namespaceURI: NamespaceURI | string): string | null;
+}
+/**
+ * @todo This is in the `lib` directory because it's a cross-cutting concern,
+ * applicable to:
+ *
+ * - Parsing XML into a useful runtime data model (usage which motivated initial
+ *   development of this class)
+ * - Serializing XML from a runtime data model (also motivated initial dev)
+ * - `@getodk/xpath` (internal) e.g. references to
+ *   {@link https://www.w3.org/TR/REC-xml-names/#NT-QName | QName} in various
+ *   parts of XPath expression _syntax_, as well as various parts of the package
+ *   interpreting those parts of syntax
+ * - `@getodk/xpath` (cross-package), e.g. in aspects of the
+ *   {@link XPathDOMAdapter} APIs, and implementations thereof
+ * - A zillion potential optimizations, e.g. where names are useful in a lookup
+ *   table (or used in conjunction with other information to construct keys for
+ *   same)
+ *
+ * @todo As a cross-cutting concern, there are subtle but important differences
+ * between certain XPath and XML semantics around expressions of a "null"
+ * {@link prefix}. E.g. in the expression `/foo`, **technically** the `foo` Step
+ * should select child elements _in the null namespace_, whereas in most other
+ * cases a null prefix (when explicitly assigned `null`, rather than
+ * {@link DeferredPrefix | deferred for later resolution}) is expected to
+ * correspond _to the default namespace_ (whatever that is in the context of the
+ * {@link QualifiedName | qualified-named thing}).
+ *
+ * @todo As a mechanism for many optimizations, an evolution of this class would
+ * be **BY FAR** most useful if it can be treated as a _value type_, despite
+ * challenges using non-primitives as such in a JS runtime. To be clear: it
+ * would be most useful if every instance of {@link QualifiedName} having the
+ * same property values (or in some cases, the same combined
+ * {@link namespaceURI}/{@link localName} or combined
+ * {@link prefix}/{@link localName}) would also have _reference equality_ with
+ * other instances having the same property values (or pertinent subset
+ * thereof). Making a somewhat obvious point explicit: this would be
+ * particularly useful in cases where a lookup table is implemented as a native
+ * {@link Map}, where using {@link QualifiedName} as a key would break
+ * expectations (and probably quite a lot of functionality!) if 2+ equivalent
+ * keys mapped to different values.
+ *
+ * @todo Where we would want to treat instances as a value type, it would be
+ * useful to look at prior art for representation of the same data as a string.
+ * One frame of reference worth looking at is
+ * {@link https://www.w3.org/TR/xpath-30/#prod-xpath30-URIQualifiedName | XPath 3.0's URIQualifiedName}
+ * (but note that this syntax is mutually exclusive with the prefixed `QName`).
+ */
+export declare class QualifiedName implements DeferredPrefixedQualifiedNameSource {
+    private readonly defaultPrefixResolutionOptions;
+    readonly namespaceURI: NamespaceURI;
+    /**
+     * @see {@link SourcePrefixUnspecified}, {@link DeferredPrefix}
+     */
+    readonly prefix: DeferredPrefix;
+    readonly localName: string;
+    constructor(source: QualifiedNameSource);
+    /**
+     * @todo at time of writing, it's not expected we will actually supply
+     * {@link options} in calls to this method! Current calls are from definitions
+     * whose prefixes are known at parse time (i.e. they are prefixed in the
+     * source XML from which they're parsed).
+     *
+     * The intent of accepting the options here now is to leave a fairly large
+     * breadcrumb, for any use case where we might want to serialize XML from
+     * artificially constructed DOM-like trees (e.g. `StaticNode` implementations
+     * defined by parsing non-XML external secondary instances such as CSV and
+     * GeoJSON). AFAIK this doesn't correspond to any known feature in the "like
+     * Collect" scope, but it could have implications for inspecting form details
+     * in e.g. "debug/form design/dev mode" scenarios.
+     */
+    getPrefixedName(options?: PrefixResolutionOptions): string;
+}
+export {};

package/dist/lib/names/UnprefixedXFormsName.d.ts

@@ -0,0 +1,4 @@
+import { QualifiedName } from './QualifiedName.ts';
+export declare class UnprefixedXFormsName extends QualifiedName {
+    constructor(localName: string);
+}

package/dist/lib/number-parsers.d.ts

@@ -0,0 +1,2 @@
+export declare const parseToInteger: (value: string | null) => number | null;
+export declare const parseToFloat: (value: string | null) => number | null;

package/dist/lib/reactivity/createInstanceValueState.d.ts

@@ -1,40 +1,15 @@
 import { InstanceValueContext } from '../../instance/internal-api/InstanceValueContext.ts';
 import { SimpleAtomicState } from './types.ts';
-type InitialValueSource = 'FORM_DEFAULT' | 'PRIMARY_INSTANCE';
-export interface InstanceValueStateOptions {
-    /**
-     * Specifies the source of a {@link createInstanceValueState} signal's initial
-     * value state, where:
-     *
-     * - 'FORM_DEFAULT': Derives the initial state from the form's definition of
-     *   the node itself. This is the default option, appropriate when
-     *   initializing a form without additional primary instance data. In other
-     *   words, this value should not be used for edits.
-     *
-     * - 'PRIMARY_INSTANCE': Derives the initial state from the current text
-     *   content of the {@link ValueNode.contextNode}. This option should be
-     *   specified when initializing a form with existing primary instance data,
-     *   such as when editing a previous submission.
-     *
-     * @default 'FORM_DEFAULT'
-     *
-     * Specifies whether a {@link createInstanceValueState} signal's initial state
-     * should be derived from the current text content of the
-     * {@link ValueNode.contextNode | primary instance DOM state}.
-     */
-    readonly initialValueSource?: InitialValueSource;
-}
 export type InstanceValueState = SimpleAtomicState<string>;
 /**
  * Provides a consistent interface for value nodes of any type which:
  *
  * - derives initial state from either an existing instance (e.g. for edits) or
- *   the node's definition (e.g. initializing a new submission)
+ *   the node's definition (e.g. initializing a new instance)
  * - decodes current primary instance state into the value node's runtime type
  * - encodes updated runtime values to store updated instance state
  * - initializes reactive computation of `calculate` bind expressions for those
  *   nodes defined with one
  * - prevents downstream writes to nodes in a readonly state
  */
-export declare const createInstanceValueState: (context: InstanceValueContext, options?: InstanceValueStateOptions) => InstanceValueState;
-export {};
+export declare const createInstanceValueState: (context: InstanceValueContext) => InstanceValueState;

package/dist/lib/reactivity/createItemCollection.d.ts

@@ -0,0 +1,21 @@
+import { Accessor } from 'solid-js';
+import { SelectItem } from '../../client/SelectNode.ts';
+import { RankItem } from '../../client/RankNode.ts';
+import { SelectControl } from '../../instance/SelectControl.ts';
+import { RankControl } from '../../instance/RankControl.ts';
+export type ItemCollectionControl = RankControl | SelectControl;
+type Item = RankItem | SelectItem;
+/**
+ * Creates a reactive computation of a {@link ItemCollectionControl}'s
+ * {@link Item}s, in support of the field's `valueOptions`.
+ *
+ * - The control defined with static `<item>`s will compute to an corresponding
+ *   static list of items.
+ * - The control defined with a computed `<itemset>` will compute to a reactive list
+ *   of items.
+ * - Items of both will produce {@link ItemType.label | labels} reactive to
+ *   their appropriate dependencies (whether relative to the itemset item node,
+ *   referencing a form's `itext` translations, etc).
+ */
+export declare const createItemCollection: (control: ItemCollectionControl) => Accessor<readonly Item[]>;
+export {};

package/dist/lib/xml-serialization.d.ts

@@ -1,3 +1,5 @@
+import { NamespaceDeclarationMap } from './names/NamespaceDeclarationMap.ts';
+import { QualifiedName } from './names/QualifiedName.ts';
 declare const ESCAPED_XML_TEXT_BRAND: unique symbol;
 export type EscapedXMLText = string & {
     readonly [ESCAPED_XML_TEXT_BRAND]: true;
@@ -36,6 +38,13 @@ export type EscapedXMLText = string & {
  *   reconsider this assumption.
  */
 export declare const escapeXMLText: <Text extends string>(text: Exclude<Text, EscapedXMLText>, attr?: boolean) => EscapedXMLText;
-export declare const serializeParentElementXML: (nodeName: string, serializedChildren: readonly string[]) => string;
-export declare const serializeLeafElementXML: (nodeName: string, xmlValue: EscapedXMLText) => string;
+interface SerializableElementAttribute {
+    serializeAttributeXML(): string;
+}
+interface ElementXMLSerializationOptions {
+    readonly namespaceDeclarations?: NamespaceDeclarationMap;
+    readonly attributes?: readonly SerializableElementAttribute[];
+}
+export declare const serializeParentElementXML: (qualifiedName: QualifiedName, serializedChildren: readonly string[], options?: ElementXMLSerializationOptions) => string;
+export declare const serializeLeafElementXML: (qualifiedName: QualifiedName, xmlValue: EscapedXMLText, options?: ElementXMLSerializationOptions) => string;
 export {};

package/dist/parse/XFormDOM.d.ts

@@ -29,7 +29,7 @@ export declare class XFormDOM {
     readonly secondaryInstanceElements: readonly DOMSecondaryInstanceElement[];
     readonly body: Element;
     protected constructor(sourceXML: string, options: XFormDOMOptions);
-    toJSON(): Omit<this, "head" | "html" | "title" | "toJSON" | "model" | "primaryInstanceRoot" | "primaryInstance" | "xformDocument"> & {
+    toJSON(): Omit<this, "head" | "html" | "title" | "toJSON" | "model" | "primaryInstance" | "primaryInstanceRoot" | "xformDocument"> & {
         xformDocument: string;
         html: string;
         head: string;

package/dist/parse/body/BodyDefinition.d.ts

@@ -4,7 +4,7 @@ import { DependencyContext } from '../expression/abstract/DependencyContext.ts';
 import { InputControlDefinition } from './control/InputControlDefinition.ts';
 import { RangeControlDefinition } from './control/RangeControlDefinition.ts';
 import { RankControlDefinition } from './control/RankControlDefinition.ts';
-import { AnySelectDefinition } from './control/select/SelectDefinition.ts';
+import { AnySelectControlDefinition } from './control/SelectControlDefinition.ts';
 import { TriggerControlDefinition } from './control/TriggerControlDefinition.ts';
 import { UploadControlDefinition } from './control/UploadControlDefinition.ts';
 import { LogicalGroupDefinition } from './group/LogicalGroupDefinition.ts';
@@ -17,7 +17,7 @@ export interface BodyElementParentContext {
     readonly reference: string | null;
     readonly element: Element;
 }
-export type ControlElementDefinition = AnySelectDefinition | InputControlDefinition | RangeControlDefinition | RankControlDefinition | TriggerControlDefinition | UploadControlDefinition;
+export type ControlElementDefinition = AnySelectControlDefinition | InputControlDefinition | RangeControlDefinition | RankControlDefinition | TriggerControlDefinition | UploadControlDefinition;
 type SupportedBodyElementDefinition = RepeatElementDefinition | LogicalGroupDefinition | PresentationGroupDefinition | StructuralGroupDefinition | ControlElementDefinition;
 export type AnyBodyElementDefinition = SupportedBodyElementDefinition | UnsupportedBodyElementDefinition;
 export type BodyElementDefinitionArray = readonly AnyBodyElementDefinition[];

package/dist/parse/body/appearance/rangeAppearanceParser.d.ts

@@ -0,0 +1,3 @@
+import { ParsedTokenList, TokenListParser } from '../../../lib/TokenListParser.ts';
+export declare const rangeAppearanceParser: TokenListParser<"no-ticks" | "picker" | "rating" | "vertical", "no-ticks" | "picker" | "rating" | "vertical">;
+export type RangeAppearanceDefinition = ParsedTokenList<typeof rangeAppearanceParser>;

package/dist/parse/body/control/InputControlDefinition.d.ts

@@ -6,5 +6,8 @@ export declare class InputControlDefinition extends ControlDefinition<'input'> {
     static isCompatible(localName: string): boolean;
     readonly type = "input";
     readonly appearances: InputAppearanceDefinition;
+    readonly rows: number | null;
+    readonly accuracyThreshold: number | null;
+    readonly unacceptableAccuracyThreshold: number | null;
     constructor(form: XFormDefinition, parent: BodyElementParentContext, element: Element);
 }

package/dist/parse/body/control/ItemDefinition.d.ts

@@ -0,0 +1,14 @@
+import { ItemElement } from '../../../lib/dom/query.ts';
+import { ItemLabelDefinition } from '../../text/ItemLabelDefinition.ts';
+import { XFormDefinition } from '../../XFormDefinition.ts';
+import { BodyElementDefinition } from '../BodyElementDefinition.ts';
+import { AnySelectControlDefinition } from './SelectControlDefinition.ts';
+import { RankControlDefinition } from './RankControlDefinition.ts';
+export declare class ItemDefinition extends BodyElementDefinition<'item'> {
+    readonly parent: AnySelectControlDefinition | RankControlDefinition;
+    readonly category = "support";
+    readonly type = "item";
+    readonly label: ItemLabelDefinition | null;
+    readonly value: string;
+    constructor(form: XFormDefinition, parent: AnySelectControlDefinition | RankControlDefinition, element: ItemElement);
+}

package/dist/parse/body/control/ItemsetDefinition.d.ts

@@ -0,0 +1,18 @@
+import { ItemsetElement } from '../../../lib/dom/query.ts';
+import { ItemsetNodesetExpression } from '../../expression/ItemsetNodesetExpression.ts';
+import { ItemsetValueExpression } from '../../expression/ItemsetValueExpression.ts';
+import { ItemsetLabelDefinition } from '../../text/ItemsetLabelDefinition.ts';
+import { XFormDefinition } from '../../XFormDefinition.ts';
+import { BodyElementDefinition } from '../BodyElementDefinition.ts';
+import { AnySelectControlDefinition } from './SelectControlDefinition.ts';
+import { RankControlDefinition } from './RankControlDefinition.ts';
+export declare class ItemsetDefinition extends BodyElementDefinition<'itemset'> {
+    readonly parent: AnySelectControlDefinition | RankControlDefinition;
+    readonly category = "support";
+    readonly type = "itemset";
+    readonly reference: string;
+    readonly label: ItemsetLabelDefinition | null;
+    readonly nodes: ItemsetNodesetExpression;
+    readonly value: ItemsetValueExpression;
+    constructor(form: XFormDefinition, parent: AnySelectControlDefinition | RankControlDefinition, element: ItemsetElement);
+}

package/dist/parse/body/control/RangeControlDefinition.d.ts

@@ -1,11 +1,40 @@
 import { XFormDefinition } from '../../XFormDefinition.ts';
-import { UnknownAppearanceDefinition } from '../appearance/unknownAppearanceParser.ts';
+import { RangeAppearanceDefinition } from '../appearance/rangeAppearanceParser.ts';
 import { BodyElementParentContext } from '../BodyDefinition.ts';
 import { ControlDefinition } from './ControlDefinition.ts';
+type NumericString = `${number}`;
+/**
+ * Per
+ * {@link https://getodk.github.io/xforms-spec/#body-elements | ODK XForms spec},
+ * the following attributes are required:
+ *
+ * - `start`
+ * - `end`
+ * - `step`
+ *
+ * While we also know that a `<range>` control is expected to have a bind type
+ * of either `decimal` or `int`, at this parsing stage we do not yet know which
+ * type is associated with the control. So we parse the attributes as strings,
+ * checking only that they appear to be numeric values. We also preserve the
+ * attributes' names here, for consistency with the spec.
+ *
+ * Downstream, we parse these to their appropriate numeric runtime types, and
+ * alias them to their more conventional names (i.e. "start" -> "min", "end" ->
+ * "max").
+ */
+export declare class RangeControlBoundsDefinition {
+    readonly start: NumericString;
+    readonly end: NumericString;
+    readonly step: NumericString;
+    static from(element: Element): RangeControlBoundsDefinition;
+    constructor(start: NumericString, end: NumericString, step: NumericString);
+}
 export declare class RangeControlDefinition extends ControlDefinition<'range'> {
     static isCompatible(localName: string): boolean;
     readonly type = "range";
-    readonly appearances: UnknownAppearanceDefinition;
+    readonly appearances: RangeAppearanceDefinition;
+    readonly bounds: RangeControlBoundsDefinition;
     constructor(form: XFormDefinition, parent: BodyElementParentContext, element: Element);
     toJSON(): object;
 }
+export {};

package/dist/parse/body/control/RankControlDefinition.d.ts

@@ -1,11 +1,15 @@
 import { XFormDefinition } from '../../XFormDefinition.ts';
-import { UnknownAppearanceDefinition } from '../appearance/unknownAppearanceParser.ts';
 import { BodyElementParentContext } from '../BodyDefinition.ts';
 import { ControlDefinition } from './ControlDefinition.ts';
+import { ItemsetDefinition } from './ItemsetDefinition.ts';
+import { ItemDefinition } from './ItemDefinition.ts';
+import { UnknownAppearanceDefinition } from '../appearance/unknownAppearanceParser.ts';
 export declare class RankControlDefinition extends ControlDefinition<'rank'> {
-    static isCompatible(localName: string, element: Element): boolean;
+    static isCompatible(localName: string): boolean;
     readonly type = "rank";
     readonly appearances: UnknownAppearanceDefinition;
+    readonly itemset: ItemsetDefinition | null;
+    readonly items: readonly ItemDefinition[];
     constructor(form: XFormDefinition, parent: BodyElementParentContext, element: Element);
-    toJSON(): object;
+    toJSON(): {};
 }

package/dist/parse/body/control/{select/SelectDefinition.d.ts → SelectControlDefinition.d.ts}

@@ -1,18 +1,18 @@
-import { CollectionValues } from '../../../../../../common/types/collections/CollectionValues.ts';
-import { LocalNamedElement } from '../../../../../../common/types/dom.ts';
-import { XFormDefinition } from '../../../XFormDefinition.ts';
-import { SelectAppearanceDefinition } from '../../appearance/selectAppearanceParser.ts';
-import { AnyBodyElementDefinition, BodyElementParentContext } from '../../BodyDefinition.ts';
-import { ControlDefinition } from '../ControlDefinition.ts';
+import { CollectionValues } from '../../../../../common/types/collections/CollectionValues.ts';
+import { LocalNamedElement } from '../../../../../common/types/dom.ts';
+import { XFormDefinition } from '../../XFormDefinition.ts';
+import { SelectAppearanceDefinition } from '../appearance/selectAppearanceParser.ts';
+import { AnyBodyElementDefinition, BodyElementParentContext } from '../BodyDefinition.ts';
+import { ControlDefinition } from './ControlDefinition.ts';
 import { ItemDefinition } from './ItemDefinition.ts';
 import { ItemsetDefinition } from './ItemsetDefinition.ts';
 declare const selectLocalNames: Set<"select" | "select1">;
 export type SelectType = CollectionValues<typeof selectLocalNames>;
 export interface SelectElement extends LocalNamedElement<SelectType> {
 }
-export declare class SelectDefinition<Type extends SelectType> extends ControlDefinition<Type> {
+export declare class SelectControlDefinition<Type extends SelectType> extends ControlDefinition<Type> {
     static isCompatible(localName: string, element: Element): boolean;
-    static isSelect(element: AnyBodyElementDefinition): element is AnySelectDefinition;
+    static isSelect(element: AnyBodyElementDefinition): element is AnySelectControlDefinition;
     readonly type: Type;
     readonly element: SelectElement;
     readonly appearances: SelectAppearanceDefinition;
@@ -21,5 +21,5 @@ export declare class SelectDefinition<Type extends SelectType> extends ControlDe
     constructor(form: XFormDefinition, parent: BodyElementParentContext, element: Element);
     toJSON(): {};
 }
-export type AnySelectDefinition = SelectDefinition<SelectType>;
+export type AnySelectControlDefinition = SelectControlDefinition<SelectType>;
 export {};

package/dist/parse/expression/ItemsetNodesetExpression.d.ts

@@ -1,4 +1,4 @@
-import { ItemsetDefinition } from '../body/control/select/ItemsetDefinition.ts';
+import { ItemsetDefinition } from '../body/control/ItemsetDefinition.ts';
 import { DependentExpression } from './abstract/DependentExpression.ts';
 export declare class ItemsetNodesetExpression extends DependentExpression<'nodes'> {
     constructor(itemset: ItemsetDefinition, nodesetExpression: string);

package/dist/parse/expression/ItemsetValueExpression.d.ts

@@ -1,4 +1,4 @@
-import { ItemsetDefinition } from '../body/control/select/ItemsetDefinition.ts';
+import { ItemsetDefinition } from '../body/control/ItemsetDefinition.ts';
 import { DependentExpression } from './abstract/DependentExpression.ts';
 export declare class ItemsetValueExpression extends DependentExpression<'string'> {
     readonly itemset: ItemsetDefinition;

package/dist/parse/model/BindDefinition.d.ts

@@ -3,6 +3,7 @@ import { BindComputationExpression } from '../expression/BindComputationExpressi
 import { MessageDefinition } from '../text/MessageDefinition.ts';
 import { XFormDefinition } from '../XFormDefinition.ts';
 import { BindElement } from './BindElement.ts';
+import { AnyBindPreloadDefinition } from './BindPreloadDefinition.ts';
 import { BindType, BindTypeDefinition } from './BindTypeDefinition.ts';
 import { ModelDefinition } from './ModelDefinition.ts';
 export declare class BindDefinition<T extends BindType = BindType> extends DependencyContext {
@@ -12,6 +13,7 @@ export declare class BindDefinition<T extends BindType = BindType> extends Depen
     readonly bindElement: BindElement;
     readonly type: BindTypeDefinition<T>;
     readonly parentNodeset: string | null;
+    readonly preload: AnyBindPreloadDefinition | null;
     readonly calculate: BindComputationExpression<'calculate'> | null;
     readonly readonly: BindComputationExpression<'readonly'>;
     readonly relevant: BindComputationExpression<'relevant'>;
@@ -34,5 +36,5 @@ export declare class BindDefinition<T extends BindType = BindType> extends Depen
     get reference(): string;
     get parentReference(): string | null;
     constructor(form: XFormDefinition, model: ModelDefinition, nodeset: string, bindElement: BindElement);
-    toJSON(): Omit<this, "form" | "reference" | "toJSON" | "parentReference" | "isTranslated" | "model" | "bindElement" | "parentBind">;
+    toJSON(): Omit<this, "form" | "reference" | "parentReference" | "toJSON" | "isTranslated" | "model" | "bindElement" | "parentBind">;
 }

package/dist/parse/model/BindPreloadDefinition.d.ts

@@ -0,0 +1,42 @@
+import { PartiallyKnownString } from '../../../../common/types/string/PartiallyKnownString.ts';
+import { BindElement } from './BindElement.ts';
+type PartiallyKnownPreloadParameter<Known extends string> = PartiallyKnownString<NonNullable<Known>> | Extract<Known, null>;
+interface PreloadParametersByType {
+    readonly uid: string | null;
+    readonly date: PartiallyKnownPreloadParameter<'today'>;
+    readonly timestamp: PartiallyKnownPreloadParameter<'end' | 'start'>;
+    readonly property: PartiallyKnownPreloadParameter<'deviceid' | 'email' | 'phonenumber' | 'username'>;
+}
+type PreloadType = PartiallyKnownString<keyof PreloadParametersByType>;
+type PreloadParameter<Type extends PreloadType> = Type extends keyof PreloadParametersByType ? PreloadParametersByType[Type] : string | null;
+interface PreloadInput<Type extends PreloadType> {
+    readonly type: Type;
+    readonly parameter: PreloadParameter<Type>;
+}
+/**
+ * Parsed representation of
+ * {@link https://getodk.github.io/xforms-spec/#preload-attributes | Preload Attributes}.
+ * If specified on a
+ * {@link https://getodk.github.io/xforms-spec/#bindings | binding}, this will
+ * be parsed to define:
+ *
+ * - {@link type}, a `jr:preload`
+ * - {@link parameter}, an associated `jr:preloadParams` value
+ *
+ * @todo It would probably make sense for the _definition_ to also convey:
+ *
+ * 1. Which {@link https://getodk.github.io/xforms-spec/#events | event} the
+ *    preload is semantically associated with (noting that the spec may be a tad
+ *    overzealous about this association).
+ *
+ * 2. The constant XPath expression (or other computation?) expressed by the
+ *    combined {@link type} and {@link parameter}.
+ */
+export declare class BindPreloadDefinition<Type extends PreloadType> implements PreloadInput<Type> {
+    static from(bindElement: BindElement): AnyBindPreloadDefinition | null;
+    readonly type: Type;
+    readonly parameter: PreloadParameter<Type>;
+    private constructor();
+}
+export type AnyBindPreloadDefinition = BindPreloadDefinition<'uid'> | BindPreloadDefinition<'timestamp'> | BindPreloadDefinition<'property'> | BindPreloadDefinition<string>;
+export {};