@getodk/xforms-engine 0.5.0 → 0.6.0

package/src/lib/names/NamespaceDeclaration.ts

@@ -0,0 +1,106 @@
+import { XMLNS_NAMESPACE_URI, XMLNS_PREFIX } from '@getodk/common/constants/xmlns.ts';
+import { escapeXMLText } from '../xml-serialization.ts';
+import type { NamespaceDeclarationMap } from './NamespaceDeclarationMap.ts';
+import type { NamespaceURI } from './QualifiedName.ts';
+import { QualifiedName } 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 class NamespaceDeclaration {
+	private readonly serializedXML: string;
+
+	/**
+	 * 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) {
+		const { declaredPrefix, declaredURI } = options;
+
+		/**
+		 * Represents the {@link QualifiedName} **of the {@link NamespaceDeclaration} itself, used only for consistent XML serialization logic.
+		 */
+		let qualifiedName: QualifiedName;
+
+		switch (declaredPrefix) {
+			// Declaring a "null prefix" is equivalent to the following XML syntax:
+			// `xmlns="..."`
+			case null:
+				qualifiedName = new QualifiedName({
+					namespaceURI: XMLNS_NAMESPACE_URI,
+					prefix: null,
+					localName: XMLNS_PREFIX,
+				});
+
+				break;
+
+			// Declaring a non-null prefix is equivalent to the following XML syntax:
+			// `xmlns:$declaredPrefix="..."
+			default:
+				qualifiedName = new QualifiedName({
+					namespaceURI: XMLNS_NAMESPACE_URI,
+					prefix: XMLNS_PREFIX,
+					localName: declaredPrefix,
+				});
+				break;
+		}
+
+		this.declaredPrefix = declaredPrefix;
+		this.declaredURI = declaredURI;
+
+		const serializedName = qualifiedName.getPrefixedName();
+		const serializedValue = escapeXMLText(declaredURI?.href ?? '');
+
+		this.serializedXML = ` ${serializedName}="${serializedValue}"`;
+	}
+
+	declaresNamespaceURI(namespaceURI: NamespaceURI) {
+		if (namespaceURI == null) {
+			return this.declaredURI === null;
+		}
+
+		return this.declaredURI?.href === namespaceURI.href;
+	}
+
+	serializeNamespaceDeclarationXML(options?: NamespaceDeclarationXMLSerializationOptions): string {
+		if (options?.omitDefaultNamespace && this.declaredPrefix == null) {
+			return '';
+		}
+
+		return this.serializedXML;
+	}
+}

package/src/lib/names/NamespaceDeclarationMap.ts

@@ -0,0 +1,228 @@
+import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
+import { NamespaceDeclaration } from './NamespaceDeclaration.ts';
+import type { 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.
+ */
+const DECLARE_NAMESPACE_RESULTS = {
+	SUCCESS: 'SUCCESS',
+	HOISTED: 'HOISTED',
+	DEFERRED: 'DEFERRED',
+	REDUNDANT: 'REDUNDANT',
+	CONFLICT: 'CONFLICT',
+} as const;
+
+type DeclareNamespaceResultEnum = typeof DECLARE_NAMESPACE_RESULTS;
+
+type DeclareNamespaceResult = DeclareNamespaceResultEnum[keyof DeclareNamespaceResultEnum];
+
+export class NamespaceDeclarationMap extends Map<string | null, NamespaceDeclaration> {
+	constructor(readonly subtree: NamedSubtreeDefinition) {
+		super();
+
+		this.declareNamespace(subtree);
+
+		const { attributes } = subtree;
+
+		if (attributes != null) {
+			for (const attribute of attributes.values()) {
+				this.declareNamespace(attribute);
+			}
+		}
+	}
+
+	/**
+	 * 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 {
+		const { prefix, namespaceURI } = definition.qualifiedName;
+
+		if (typeof prefix === 'symbol') {
+			return DECLARE_NAMESPACE_RESULTS.DEFERRED;
+		}
+
+		const parentNamespaceDeclarations = this.subtree.parent?.namespaceDeclarations;
+
+		if (parentNamespaceDeclarations != null) {
+			const ancestorResult = parentNamespaceDeclarations.declareNamespace(definition);
+
+			switch (ancestorResult) {
+				case DECLARE_NAMESPACE_RESULTS.CONFLICT:
+					break;
+
+				case DECLARE_NAMESPACE_RESULTS.DEFERRED:
+					return ancestorResult;
+
+				case DECLARE_NAMESPACE_RESULTS.HOISTED:
+					return ancestorResult;
+
+				case DECLARE_NAMESPACE_RESULTS.SUCCESS:
+				case DECLARE_NAMESPACE_RESULTS.REDUNDANT:
+					return DECLARE_NAMESPACE_RESULTS.HOISTED;
+
+				default:
+					throw new UnreachableError(ancestorResult);
+			}
+		}
+
+		const currentDeclaration = this.get(prefix);
+
+		if (currentDeclaration == null) {
+			this.set(
+				prefix,
+				new NamespaceDeclaration({
+					declaredPrefix: prefix,
+					declaredURI: namespaceURI,
+				})
+			);
+
+			return DECLARE_NAMESPACE_RESULTS.SUCCESS;
+		}
+
+		if (currentDeclaration.declaresNamespaceURI(namespaceURI)) {
+			return DECLARE_NAMESPACE_RESULTS.REDUNDANT;
+		}
+
+		return DECLARE_NAMESPACE_RESULTS.CONFLICT;
+	}
+
+	/**
+	 * 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 {
+		const namespace = String(namespaceURI);
+
+		// Note: this is a dynamic lookup on the _very unlikely_ chance that a
+		// lookup occurs while parsing is still in progress. It's expected that we
+		// collect all namespace declarations by the time parsing is complete, at
+		// which point we could theoretically collect a companion map where the
+		// namespace URI is used as a key. This has been deferred for now, because
+		// we'd need:
+		//
+		// 1. To know _in this class_ when parsing is complete (which seems like a
+		//    huge excess of mixed responsibilities!)
+		// 2. To resolve the "object-as-value-as-map-key" problem, which has also
+		//    been deferred.
+		for (const namespaceDeclaration of this.values()) {
+			if (String(namespaceDeclaration.declaredURI) === namespace) {
+				return namespaceDeclaration.declaredPrefix;
+			}
+		}
+
+		return this.subtree.parent?.namespaceDeclarations.lookupPrefix(namespaceURI) ?? null;
+	}
+}

package/src/lib/names/NamespaceURL.ts

@@ -0,0 +1,44 @@
+import type { NamespaceDeclaration } from './NamespaceDeclaration.ts';
+
+/**
+ * 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 class NamespaceURL extends URL {
+	static from(namespaceURI: NamespaceURL | string | null): NamespaceURL | null {
+		if (namespaceURI == null || namespaceURI === '') {
+			return null;
+		}
+
+		return new this(String(namespaceURI));
+	}
+
+	override readonly href: string;
+
+	private constructor(href: string) {
+		super(href);
+
+		this.href = href;
+	}
+}

package/src/lib/names/QualifiedName.ts

@@ -0,0 +1,170 @@
+import type { XPathDOMAdapter } from '@getodk/xpath';
+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;
+}
+
+const SOURCE_PREFIX_UNSPECIFIED = Symbol('SOURCE_PREFIX_UNSPECIFIED');
+
+/**
+ * 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}.
+ */
+// prettier-ignore
+type DeferredPrefix =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| string
+	| null
+	| SourcePrefixUnspecified;
+
+interface DeferredPrefixedQualifiedNameSource {
+	readonly namespaceURI: NamespaceURI | string;
+	readonly prefix: DeferredPrefix;
+	readonly localName: string;
+}
+
+// prettier-ignore
+export type QualifiedNameSource =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| 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 class QualifiedName implements DeferredPrefixedQualifiedNameSource {
+	private readonly defaultPrefixResolutionOptions: PrefixResolutionOptions;
+
+	readonly namespaceURI: NamespaceURI;
+
+	/**
+	 * @see {@link SourcePrefixUnspecified}, {@link DeferredPrefix}
+	 */
+	readonly prefix: DeferredPrefix;
+
+	readonly localName: string;
+
+	constructor(source: QualifiedNameSource) {
+		const { localName } = source;
+
+		let prefix = source.prefix;
+
+		if (typeof prefix === 'undefined') {
+			prefix = SOURCE_PREFIX_UNSPECIFIED;
+		}
+
+		const namespaceURI = NamespaceURL.from(source.namespaceURI);
+
+		this.namespaceURI = namespaceURI;
+		this.prefix = prefix;
+		this.localName = localName;
+
+		this.defaultPrefixResolutionOptions = {
+			lookupPrefix: () => {
+				if (prefix === SOURCE_PREFIX_UNSPECIFIED) {
+					throw new Error(`Failed to resolve prefix for namespace URI: ${String(namespaceURI)}`);
+				}
+
+				return prefix;
+			},
+		};
+	}
+
+	/**
+	 * @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 = this.defaultPrefixResolutionOptions): string {
+		const { namespaceURI, localName } = this;
+		const prefix = options.lookupPrefix(namespaceURI);
+
+		if (prefix == null) {
+			return localName;
+		}
+
+		return `${prefix}:${localName}`;
+	}
+}

package/src/lib/number-parsers.ts

@@ -0,0 +1,25 @@
+export const parseToInteger = (value: string | null): number | null => {
+	if (value === null) {
+		return null;
+	}
+
+	const parsed = Number(value);
+	if (typeof value !== 'string' || value.trim() === '' || !Number.isInteger(parsed)) {
+		throw new Error(`Expected an integer, but got: ${value}`);
+	}
+
+	return parsed;
+};
+
+export const parseToFloat = (value: string | null): number | null => {
+	if (value === null) {
+		return null;
+	}
+
+	const parsed = Number(value);
+	if (typeof value !== 'string' || value.trim() === '' || Number.isNaN(parsed)) {
+		throw new Error(`Expected a float, but got: ${value}`);
+	}
+
+	return parsed;
+};

package/src/lib/reactivity/createInstanceValueState.ts

@@ -8,6 +8,13 @@ import type { SimpleAtomicState, SimpleAtomicStateSetter } from './types.ts';
 
 type InitialValueSource = 'FORM_DEFAULT' | 'PRIMARY_INSTANCE';
 
+/**
+ * @todo {@link InitialValueSource} naming leaves a lot to be desired. As described in {@link InstanceValueStateOptions.initialValueSource}, this check (for now) will effectively answer the question: "are we **NOT** editing instance state (e.g. a submission)?". This answer, in turn, determines whether to {@link setPreloadUIDValue}
+ */
+const isInstanceFirstLoad = (valueSource?: InitialValueSource) => {
+	return valueSource === 'FORM_DEFAULT';
+};
+
 export interface InstanceValueStateOptions {
 	/**
 	 * Specifies the source of a {@link createInstanceValueState} signal's initial
@@ -106,10 +113,47 @@ const guardDownstreamReadonlyWrites = (
 	return [getValue, setValue];
 };
 
+/**
+ * Per {@link https://getodk.github.io/xforms-spec/#preload-attributes:~:text=concatenation%20of%20%E2%80%98uuid%3A%E2%80%99%20and%20uuid()}
+ */
+const PRELOAD_UID_EXPRESSION = 'concat("uuid:", uuid())';
+
+/**
+ * @todo This is a temporary one-off, until we support the full range of
+ * {@link https://getodk.github.io/xforms-spec/#preload-attributes | preloads}.
+ *
+ * @todo ALSO, IMPORTANTLY(!): the **call site** for this function is
+ * semantically where we would expect to trigger a
+ * {@link https://getodk.github.io/xforms-spec/#event:odk-instance-first-load | odk-instance-first-load event},
+ * _and compute_ preloads semantically associated with that event.
+ */
+const setPreloadUIDValue = (
+	context: InstanceValueContext,
+	valueState: RelevantValueState,
+	options: InstanceValueStateOptions
+): void => {
+	const { preload } = context.definition.bind;
+
+	if (preload?.type !== 'uid' || !isInstanceFirstLoad(options?.initialValueSource)) {
+		return;
+	}
+
+	const preloadUIDValue = context.evaluator.evaluateString(PRELOAD_UID_EXPRESSION, {
+		contextNode: context.contextNode,
+	});
+
+	const [, setValue] = valueState;
+
+	setValue(preloadUIDValue);
+};
+
 /**
  * Defines a reactive effect which writes the result of `calculate` bind
  * computations to the provided value setter, on initialization and any
  * subsequent reactive update.
+ *
+ * @see {@link setPreloadUIDValue} for important details about spec ordering of
+ * events and computations.
  */
 const createCalculation = (
 	context: InstanceValueContext,
@@ -153,6 +197,12 @@ export const createInstanceValueState = (
 		const initialValue = getInitialValue(context, options);
 		const baseValueState = createSignal(initialValue);
 		const relevantValueState = createRelevantValueState(context, baseValueState);
+
+		/**
+		 * @see {@link setPreloadUIDValue} for important details about spec ordering of events and computations.
+		 */
+		setPreloadUIDValue(context, relevantValueState, options);
+
 		const { calculate } = context.definition.bind;
 
 		if (calculate != null) {