@getodk/xforms-engine 0.4.0 → 0.6.0

package/dist/integration/xpath/static-dom/StaticNode.d.ts

@@ -0,0 +1,33 @@
+import { XPathNodeKindKey } from '@getodk/xpath';
+import { XFormsXPathNode } from '../adapter/XFormsXPathNode.ts';
+import { StaticAttribute } from './StaticAttribute.ts';
+import { StaticDocument } from './StaticDocument.ts';
+import { StaticElement } from './StaticElement.ts';
+import { StaticText } from './StaticText.ts';
+export type StaticNodeKind = 'document' | 'element' | 'attribute' | 'text';
+export type StaticNodeType<Kind extends StaticNodeKind> = `static-${Kind}`;
+export declare abstract class StaticNode<Kind extends StaticNodeKind> implements XFormsXPathNode {
+    abstract readonly [XPathNodeKindKey]: Kind;
+    abstract readonly nodeType: StaticNodeType<Kind>;
+    /**
+     * A concrete {@link StaticDocument} instance, representing the topmost node
+     * of a static document tree, containing all of:
+     *
+     * - {@link root}
+     * - {@link children}
+     * - any {@link StaticChildNode} descendants of either of the above
+     */
+    abstract readonly rootDocument: StaticDocument;
+    /**
+     * A concrete {@link StaticElement} instance, representing the single,
+     * immediate child of {@link rootDocument}, containing all other descendants
+     * of its document tree.
+     */
+    abstract readonly root: StaticElement;
+    abstract readonly children: readonly StaticChildNode[] | null;
+    getXPathChildNodes(): readonly StaticChildNode[];
+    abstract getXPathValue(): string;
+}
+export type AnyStaticNode = StaticDocument | StaticElement | StaticAttribute | StaticText;
+export type StaticParentNode = StaticDocument | StaticElement;
+export type StaticChildNode = StaticElement | StaticText;

package/dist/integration/xpath/static-dom/StaticText.d.ts

@@ -0,0 +1,16 @@
+import { XPathNodeKindKey } from '@getodk/xpath';
+import { XFormsXPathText } from '../adapter/XFormsXPathNode.ts';
+import { StaticDocument } from './StaticDocument.ts';
+import { StaticElement } from './StaticElement.ts';
+import { StaticNode } from './StaticNode.ts';
+export declare class StaticText extends StaticNode<'text'> implements XFormsXPathText {
+    readonly parent: StaticElement;
+    readonly value: string;
+    readonly [XPathNodeKindKey] = "text";
+    readonly nodeType = "static-text";
+    readonly rootDocument: StaticDocument;
+    readonly root: StaticElement;
+    readonly children: null;
+    constructor(parent: StaticElement, value: string);
+    getXPathValue(): string;
+}

package/dist/lib/client-reactivity/submission/createInstanceSubmissionState.d.ts

@@ -0,0 +1,3 @@
+import { SubmissionState } from '../../../client/submission/SubmissionState.ts';
+import { ClientReactiveSubmittableInstance } from '../../../instance/internal-api/submission/ClientReactiveSubmittableInstance.ts';
+export declare const createInstanceSubmissionState: (node: ClientReactiveSubmittableInstance) => SubmissionState;

package/dist/lib/client-reactivity/submission/createLeafNodeSubmissionState.d.ts

@@ -0,0 +1,3 @@
+import { SubmissionState } from '../../../client/submission/SubmissionState.ts';
+import { ClientReactiveSubmittableLeafNode } from '../../../instance/internal-api/submission/ClientReactiveSubmittableLeafNode.ts';
+export declare const createLeafNodeSubmissionState: <Value>(node: ClientReactiveSubmittableLeafNode<Value>) => SubmissionState;

package/dist/lib/client-reactivity/submission/createNodeRangeSubmissionState.d.ts

@@ -0,0 +1,4 @@
+import { SubmissionState } from '../../../client/submission/SubmissionState.ts';
+import { ClientReactiveSubmittableParentNode } from '../../../instance/internal-api/submission/ClientReactiveSubmittableParentNode.ts';
+import { RepeatInstance } from '../../../instance/repeat/RepeatInstance.ts';
+export declare const createNodeRangeSubmissionState: (node: ClientReactiveSubmittableParentNode<RepeatInstance>) => SubmissionState;

package/dist/lib/client-reactivity/submission/createParentNodeSubmissionState.d.ts

@@ -0,0 +1,4 @@
+import { SubmissionState } from '../../../client/submission/SubmissionState.ts';
+import { GeneralChildNode } from '../../../instance/hierarchy.ts';
+import { ClientReactiveSubmittableParentNode } from '../../../instance/internal-api/submission/ClientReactiveSubmittableParentNode.ts';
+export declare const createParentNodeSubmissionState: (node: ClientReactiveSubmittableParentNode<GeneralChildNode>) => SubmissionState;

package/dist/lib/client-reactivity/submission/createRootSubmissionState.d.ts

@@ -0,0 +1,3 @@
+import { SubmissionState } from '../../../client/submission/SubmissionState.ts';
+import { Root } from '../../../instance/Root.ts';
+export declare const createRootSubmissionState: (node: Root) => SubmissionState;

package/dist/lib/client-reactivity/submission/createValueNodeSubmissionState.d.ts

@@ -0,0 +1,3 @@
+import { SubmissionState } from '../../../client/submission/SubmissionState.ts';
+import { ClientReactiveSubmittableValueNode } from '../../../instance/internal-api/submission/ClientReactiveSubmittableValueNode.ts';
+export declare const createValueNodeSubmissionState: (node: ClientReactiveSubmittableValueNode) => SubmissionState;

package/dist/lib/client-reactivity/submission/prepareSubmission.d.ts

@@ -0,0 +1,8 @@
+import { SubmissionChunkedType } from '../../../client/submission/SubmissionOptions.ts';
+import { SubmissionResult } from '../../../client/submission/SubmissionResult.ts';
+import { ClientReactiveSubmittableInstance } from '../../../instance/internal-api/submission/ClientReactiveSubmittableInstance.ts';
+export interface PrepeareSubmissionOptions<ChunkedType extends SubmissionChunkedType> {
+    readonly chunked: ChunkedType;
+    readonly maxSize: number;
+}
+export declare const prepareSubmission: <ChunkedType extends SubmissionChunkedType>(instanceRoot: ClientReactiveSubmittableInstance, options: PrepeareSubmissionOptions<ChunkedType>) => SubmissionResult<ChunkedType>;

package/dist/lib/codecs/DecimalValueCodec.d.ts

@@ -0,0 +1,6 @@
+import { ValueCodec } from './ValueCodec.ts';
+export type DecimalInputValue = bigint | number | string | null;
+export type DecimalRuntimeValue = number | null;
+export declare class DecimalValueCodec extends ValueCodec<'decimal', DecimalRuntimeValue, DecimalInputValue> {
+    constructor();
+}

package/dist/lib/codecs/Geopoint/Geopoint.d.ts

@@ -0,0 +1,48 @@
+/**
+ * This abstract class defines the minimal behavior for a default geopoint.
+ * It can be expanded later to support units (e.g., degrees or meters),
+ * which would also serve as documentation to clarify what each value represents.
+ */
+declare abstract class SemanticValue<Semantic extends string, Value extends number | null> {
+    readonly value: Value;
+    abstract readonly semantic: Semantic;
+    constructor(value: Value);
+}
+declare class Latitude extends SemanticValue<'latitude', number> {
+    readonly semantic = "latitude";
+}
+declare class Longitude extends SemanticValue<'longitude', number> {
+    readonly semantic = "longitude";
+}
+declare class Altitude<Value extends number | null = number> extends SemanticValue<'altitude', Value> {
+    readonly semantic = "altitude";
+}
+declare class Accuracy<Value extends number | null = number> extends SemanticValue<'accuracy', Value> {
+    readonly semantic = "accuracy";
+}
+export interface GeopointValue {
+    readonly latitude: number;
+    readonly longitude: number;
+    readonly altitude: number | null;
+    readonly accuracy: number | null;
+}
+export type GeopointRuntimeValue = GeopointValue | null;
+export type GeopointInputValue = GeopointRuntimeValue | string;
+type GeopointTuple = readonly [
+    latitude: Latitude,
+    longitude: Longitude,
+    altitude: Altitude<null> | Altitude<number>,
+    accuracy: Accuracy
+] | readonly [latitude: Latitude, longitude: Longitude, altitude: Altitude] | readonly [latitude: Latitude, longitude: Longitude];
+export declare class Geopoint {
+    private readonly internalValue;
+    constructor(coordinates: GeopointValue);
+    getTuple(): GeopointTuple;
+    getRuntimeValue(): GeopointRuntimeValue;
+    private isValidDegrees;
+    private isValidNumber;
+    private static isNullLocation;
+    static parseString(value: string): GeopointRuntimeValue;
+    static toCoordinatesString(value: GeopointInputValue): string;
+}
+export {};

package/dist/lib/codecs/Geopoint/GeopointValueCodec.d.ts

@@ -0,0 +1,5 @@
+import { ValueCodec } from '../ValueCodec.ts';
+import { GeopointInputValue, GeopointRuntimeValue } from './Geopoint.ts';
+export declare class GeopointValueCodec extends ValueCodec<'geopoint', GeopointRuntimeValue, GeopointInputValue> {
+    constructor();
+}

package/dist/lib/codecs/IntValueCodec.d.ts

@@ -0,0 +1,6 @@
+import { ValueCodec } from './ValueCodec.ts';
+export type IntInputValue = bigint | number | string | null;
+export type IntRuntimeValue = bigint | null;
+export declare class IntValueCodec extends ValueCodec<'int', IntRuntimeValue, IntInputValue> {
+    constructor();
+}

package/dist/lib/codecs/NoteCodec.d.ts

@@ -0,0 +1,8 @@
+import { ValueType } from '../../client/ValueType.ts';
+import { RuntimeInputValue, RuntimeValue, SharedValueCodec } from './getSharedValueCodec.ts';
+import { ValueCodec } from './ValueCodec.ts';
+export type NoteRuntimeValue<V extends ValueType> = RuntimeValue<V> | null;
+export type NoteInputValue<V extends ValueType> = RuntimeInputValue<V> | RuntimeValue<V> | null;
+export declare class NoteCodec<V extends ValueType> extends ValueCodec<V, NoteRuntimeValue<V>, NoteInputValue<V>> {
+    constructor(baseCodec: SharedValueCodec<V>);
+}

package/dist/lib/codecs/RangeCodec.d.ts

@@ -0,0 +1,8 @@
+import { RangeNodeDefinition, RangeValueType } from '../../parse/model/RangeNodeDefinition.ts';
+import { RuntimeInputValue, RuntimeValue, SharedValueCodec } from './getSharedValueCodec.ts';
+import { ValueCodec } from './ValueCodec.ts';
+export type RangeRuntimeValue<V extends RangeValueType> = RuntimeValue<V>;
+export type RangeInputValue<V extends RangeValueType> = RuntimeInputValue<V>;
+export declare class RangeCodec<V extends RangeValueType> extends ValueCodec<V, RangeRuntimeValue<V>, RangeInputValue<V>> {
+    constructor(baseCodec: SharedValueCodec<V>, definition: RangeNodeDefinition<V>);
+}

package/dist/lib/codecs/StringValueCodec.d.ts

@@ -0,0 +1,4 @@
+import { ValueCodec } from './ValueCodec.ts';
+export declare class StringValueCodec extends ValueCodec<'string', string, string> {
+    constructor();
+}

package/dist/lib/codecs/TriggerCodec.d.ts

@@ -0,0 +1,7 @@
+import { ValueCodec } from './ValueCodec.ts';
+export type TriggerValueType = 'string';
+export type TriggerRuntimeValue = boolean;
+export type TriggerInputValue = boolean | '' | null;
+export declare class TriggerCodec extends ValueCodec<TriggerValueType, TriggerRuntimeValue, TriggerInputValue> {
+    constructor();
+}

package/dist/lib/codecs/ValueArrayCodec.d.ts

@@ -0,0 +1,11 @@
+import { ValueType } from '../../client/ValueType.ts';
+import { RuntimeValue, SharedValueCodec } from './getSharedValueCodec.ts';
+import { CodecDecoder, CodecEncoder, ValueCodec } from './ValueCodec.ts';
+export type SplitInstanceValues = (value: string) => readonly string[];
+export type JoinInstnaceValues = (values: readonly string[]) => string;
+export type RuntimeItemValue<V extends ValueType> = NonNullable<RuntimeValue<V>>;
+export type RuntimeValues<V extends ValueType> = ReadonlyArray<RuntimeItemValue<V>>;
+export declare abstract class ValueArrayCodec<V extends ValueType, Values extends RuntimeValues<V> = RuntimeValues<V>> extends ValueCodec<V, Values, Values> {
+    readonly decodeItemValue: CodecDecoder<RuntimeItemValue<V>>;
+    constructor(baseCodec: SharedValueCodec<V>, encodeValue: CodecEncoder<Values>, decodeValue: CodecDecoder<Values>);
+}

package/dist/lib/codecs/ValueCodec.d.ts

@@ -0,0 +1,30 @@
+import { Accessor } from 'solid-js';
+import { ValueType } from '../../client/ValueType.ts';
+import { DecodeInstanceValue } from '../../instance/internal-api/InstanceValueContext.ts';
+import { SimpleAtomicState } from '../reactivity/types.ts';
+export type CodecEncoder<RuntimeInputValue> = (input: RuntimeInputValue) => string;
+export type CodecDecoder<RuntimeValue> = (value: string) => RuntimeValue;
+type RuntimeValueAccessor<RuntimeValue> = Accessor<RuntimeValue>;
+export type RuntimeValueSetter<RuntimeValue extends RuntimeInputValue, RuntimeInputValue = RuntimeValue> = (input: RuntimeInputValue) => RuntimeValue;
+export type RuntimeValueState<RuntimeValue extends RuntimeInputValue, RuntimeInputValue = RuntimeValue> = readonly [
+    get: RuntimeValueAccessor<RuntimeValue>,
+    set: RuntimeValueSetter<RuntimeValue, RuntimeInputValue>
+];
+export type CreateRuntimeValueState<RuntimeValue extends RuntimeInputValue, RuntimeInputValue = RuntimeValue> = (instanceState: SimpleAtomicState<string>) => RuntimeValueState<RuntimeValue, RuntimeInputValue>;
+type RuntimeValueStateFactory<RuntimeValue extends RuntimeInputValue, RuntimeInputValue = RuntimeValue> = (encodeValue: CodecEncoder<RuntimeInputValue>, decodeValue: CodecDecoder<RuntimeValue>) => CreateRuntimeValueState<RuntimeValue, RuntimeInputValue>;
+type DecodeInstanceValueFactory<RuntimeValue extends RuntimeInputValue, RuntimeInputValue = RuntimeValue> = (encodeValue: CodecEncoder<RuntimeInputValue>, decodeValue: CodecDecoder<RuntimeValue>) => DecodeInstanceValue;
+interface ValueCodecOptions<RuntimeValue extends RuntimeInputValue, RuntimeInputValue> {
+    readonly decodeInstanceValueFactory?: DecodeInstanceValueFactory<RuntimeValue, RuntimeInputValue>;
+    readonly runtimeValueStateFactory?: RuntimeValueStateFactory<RuntimeValue, RuntimeInputValue>;
+}
+export declare abstract class ValueCodec<V extends ValueType, RuntimeValue extends RuntimeInputValue, RuntimeInputValue = RuntimeValue> {
+    readonly valueType: V;
+    readonly encodeValue: CodecEncoder<RuntimeInputValue>;
+    readonly decodeValue: CodecDecoder<RuntimeValue>;
+    protected readonly defaultRuntimeValueStateFactory: RuntimeValueStateFactory<RuntimeValue, RuntimeInputValue>;
+    protected readonly defaultDecodeInstanceValueFactory: DecodeInstanceValueFactory<RuntimeValue, RuntimeInputValue>;
+    readonly decodeInstanceValue: DecodeInstanceValue;
+    readonly createRuntimeValueState: CreateRuntimeValueState<RuntimeValue, RuntimeInputValue>;
+    constructor(valueType: V, encodeValue: CodecEncoder<RuntimeInputValue>, decodeValue: CodecDecoder<RuntimeValue>, options?: ValueCodecOptions<RuntimeValue, RuntimeInputValue>);
+}
+export {};

package/dist/lib/codecs/ValueTypePlaceholderCodec.d.ts

@@ -0,0 +1,12 @@
+import { ValueType } from '../../client/ValueType.ts';
+import { ValueCodec } from './ValueCodec.ts';
+/**
+ * Provides fallback functionality where a {@link ValueCodec} is expected, for
+ * those {@link ValueType | value types} which are still pending implementation.
+ * This allows consistent use of the {@link ValueCodec} interface while
+ * maintaining the current behavior of treating those unimplemented value types
+ * as string values.
+ */
+export declare class ValueTypePlaceholderCodec<V extends ValueType> extends ValueCodec<V, string, string> {
+    constructor(valueType: V);
+}

package/dist/lib/codecs/getNoteCodec.d.ts

@@ -0,0 +1,3 @@
+import { ValueType } from '../../client/ValueType.ts';
+import { NoteCodec } from './NoteCodec.ts';
+export declare const getNoteCodec: <V extends ValueType>(valueType: V) => NoteCodec<V>;

package/dist/lib/codecs/getSelectCodec.d.ts

@@ -0,0 +1,5 @@
+import { SelectDefinition } from '../../client/SelectNode.ts';
+import { MultipleValueItemCodec } from './items/MultipleValueItemCodec.ts';
+import { SingleValueItemCodec } from './items/SingleValueItemCodec.ts';
+export type SelectCodec = MultipleValueItemCodec | SingleValueItemCodec;
+export declare const getSelectCodec: (definition: SelectDefinition<"string">) => SelectCodec;

package/dist/lib/codecs/getSharedValueCodec.d.ts

@@ -0,0 +1,48 @@
+import { ValueType } from '../../client/ValueType.ts';
+import { DecimalInputValue, DecimalRuntimeValue } from './DecimalValueCodec.ts';
+import { GeopointInputValue, GeopointRuntimeValue } from './Geopoint/Geopoint.ts';
+import { IntInputValue, IntRuntimeValue } from './IntValueCodec.ts';
+import { ValueCodec } from './ValueCodec.ts';
+interface RuntimeValuesByType {
+    readonly string: string;
+    readonly int: IntRuntimeValue;
+    readonly decimal: DecimalRuntimeValue;
+    readonly boolean: string;
+    readonly date: string;
+    readonly time: string;
+    readonly dateTime: string;
+    readonly geopoint: GeopointRuntimeValue;
+    readonly geotrace: string;
+    readonly geoshape: string;
+    readonly binary: string;
+    readonly barcode: string;
+    readonly intent: string;
+}
+export type RuntimeValue<V extends ValueType> = RuntimeValuesByType[V];
+interface RuntimeInputValuesByType {
+    readonly string: string;
+    readonly int: IntInputValue;
+    readonly decimal: DecimalInputValue;
+    readonly boolean: string;
+    readonly date: string;
+    readonly time: string;
+    readonly dateTime: string;
+    readonly geopoint: GeopointInputValue;
+    readonly geotrace: string;
+    readonly geoshape: string;
+    readonly binary: string;
+    readonly barcode: string;
+    readonly intent: string;
+}
+export type RuntimeInputValue<V extends ValueType> = RuntimeInputValuesByType[V];
+type SharedValueCodecs = {
+    readonly [V in ValueType]: ValueCodec<V, RuntimeValue<V>, RuntimeInputValue<V>>;
+};
+export type SharedValueCodec<V extends ValueType> = SharedValueCodecs[V];
+/**
+ * Provides codecs for each {@link ValueType | value type}, for nodes with a
+ * common representation of those value types.
+ */
+export declare const sharedValueCodecs: SharedValueCodecs;
+export declare const getSharedValueCodec: <V extends ValueType>(valueType: V) => SharedValueCodec<V>;
+export {};

package/dist/lib/codecs/items/BaseItemCodec.d.ts

@@ -0,0 +1,9 @@
+import { ValueType } from '../../../client/ValueType.ts';
+import { SharedValueCodec } from '../getSharedValueCodec.ts';
+import { ValueArrayCodec } from '../ValueArrayCodec.ts';
+import { CodecDecoder, CodecEncoder } from '../ValueCodec.ts';
+export type BaseItemValueType = 'string';
+export type UnsupportedBaseItemValueType = Exclude<ValueType, BaseItemValueType>;
+export declare abstract class BaseItemCodec<Values extends readonly string[] = readonly string[]> extends ValueArrayCodec<BaseItemValueType, Values> {
+    constructor(baseCodec: SharedValueCodec<'string'>, encodeValue: CodecEncoder<Values>, decodeValue: CodecDecoder<Values>);
+}

package/dist/lib/codecs/items/MultipleValueItemCodec.d.ts

@@ -0,0 +1,14 @@
+import { SharedValueCodec } from '../getSharedValueCodec.ts';
+import { BaseItemCodec } from './BaseItemCodec.ts';
+/**
+ * Value codec implementation for `<select>` and `<odk:rank>` controls.
+ *
+ * This generalizes the application of a {@link SharedValueCodec} implementation
+ * over individual select and rank values, where those values are serialized as a
+ * whitespace-separated list. All other encoding and decoding logic is deferred
+ * to the provided {@link baseCodec}, ensuring that select and rank value types are
+ * treated consistently with the same underlying data types for other controls.
+ */
+export declare class MultipleValueItemCodec extends BaseItemCodec<readonly string[]> {
+    constructor(baseCodec: SharedValueCodec<'string'>);
+}

package/dist/lib/codecs/items/SingleValueItemCodec.d.ts

@@ -0,0 +1,24 @@
+import { SharedValueCodec } from '../getSharedValueCodec.ts';
+import { BaseItemCodec } from './BaseItemCodec.ts';
+export type SingleValueSelectRuntimeValues = readonly [] | readonly [string];
+/**
+ * @see {@link encodeValueFactory}
+ */
+type SingleValueSelectCodecValues = SingleValueSelectRuntimeValues | readonly string[];
+/**
+ * Value codec implementation for `<select1>` controls.
+ *
+ * Note: this implementation is a specialization of the same principles
+ * underlying {@link MultipleValueItemCodec}. It is implemented separately:
+ *
+ * 1. to address a semantic difference between `<select>` and `<select1>`
+ *    values: the former are serialized as a space-separated list, but that does
+ *    not apply to the latter;
+ *
+ * 2. as an optimization, as the more general implementation performs poorly on
+ *    forms which we monitor for performance.
+ */
+export declare class SingleValueItemCodec extends BaseItemCodec<SingleValueSelectCodecValues> {
+    constructor(baseCodec: SharedValueCodec<'string'>);
+}
+export {};

package/dist/lib/dom/query.d.ts

@@ -1,5 +1,4 @@
 import { KnownAttributeLocalNamedElement, LocalNamedElement } from '../../../../common/types/dom.ts';
-import { SelectElement } from '../../parse/body/control/select/SelectDefinition';
 export interface HintElement extends LocalNamedElement<'hint'> {
 }
 export interface ItemElement extends LocalNamedElement<'item'> {
@@ -17,9 +16,12 @@ export interface RepeatElement extends KnownAttributeLocalNamedElement<'repeat',
 export interface ValueElement extends LocalNamedElement<'value'> {
 }
 export declare const getHintElement: (parent: Element) => HintElement | null;
-export declare const getItemElements: (parent: SelectElement) => readonly ItemElement[];
+export declare const getItemElements: (parent: Element) => readonly ItemElement[];
 export declare const getItemsetElement: (parent: Element) => ItemsetElement | null;
 export declare const getLabelElement: (parent: Element) => LabelElement | null;
 export declare const getRepeatGroupLabelElement: (parent: Element) => RepeatGroupLabelElement | null;
 export declare const getRepeatElement: (parent: Element) => RepeatElement | null;
 export declare const getValueElement: (parent: ItemElement | ItemsetElement) => ValueElement | null;
+export interface SubmissionElement extends LocalNamedElement<'submission'> {
+}
+export declare const getSubmissionElement: (parent: Element) => SubmissionElement | null;

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

@@ -0,0 +1,45 @@
+import { NamespaceURI } from './QualifiedName.ts';
+interface NamespaceDeclarationXMLSerializationOptions {
+    readonly omitDefaultNamespace?: boolean;
+}
+export interface NamespaceDeclarationOptions {
+    readonly declaredPrefix: string | null;
+    readonly declaredURI: NamespaceURI;
+}
+/**
+ * Provides a generalized representation of an XML namespace declaration, which
+ * can be used for:
+ *
+ * - Resolution of a declared namespace URI, by its declared prefix
+ * - Resolution of a declared namespace prefix associated with its namespace URI
+ * - Scoped resolution of same in an arbitrary DOM-like tree of nodes (or
+ *   representations thereof)
+ * - Serialization of the namespace declaration as an XML representation, as
+ *   part of broader XML serialization logic from an arbitrary DOM-like tree of
+ *   nodes (or representations thereof)
+ *
+ * @see {@link NamespaceDeclarationMap} for details on scoped usage
+ */
+export declare class NamespaceDeclaration {
+    private readonly serializedXML;
+    /**
+     * A namespace is declared as either:
+     *
+     * - a "default" namespace (for which no prefix is declared, in which case
+     *   this value will be `null`)
+     *
+     * - a namespace prefix (for which the prefix can be used to reference the
+     *   declared namespace, in which case this value will be a `string`)
+     */
+    readonly declaredPrefix: string | null;
+    /**
+     * A namespace is declared for a {@link NamespaceURI}, i.e. either a
+     * {@link URL} or `null`, where `null` corresponds to the "null namespace"
+     * (i.e. `xmlns=""` or `xmlns:prefix=""`, in serialized XML).
+     */
+    readonly declaredURI: NamespaceURI;
+    constructor(options: NamespaceDeclarationOptions);
+    declaresNamespaceURI(namespaceURI: NamespaceURI): boolean;
+    serializeNamespaceDeclarationXML(options?: NamespaceDeclarationXMLSerializationOptions): string;
+}
+export {};

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();
+}