@getodk/xforms-engine 0.14.0 → 0.15.0

package/src/instance/abstract/InstanceNode.ts

@@ -13,6 +13,7 @@ import type {
 	XFormsXPathPrimaryInstanceNodeKind,
 } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
 import type { PrimaryInstanceXPathNode } from '../../integration/xpath/adapter/kind.ts';
+import type { StaticAttribute } from '../../integration/xpath/static-dom/StaticAttribute.ts';
 import type { StaticDocument } from '../../integration/xpath/static-dom/StaticDocument.ts';
 import type { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
 import type { MaterializedChildren } from '../../lib/reactivity/materializeCurrentStateChildren.ts';
@@ -24,6 +25,7 @@ import { createReactiveScope } from '../../lib/reactivity/scope.ts';
 import type { SimpleAtomicState } from '../../lib/reactivity/types.ts';
 import { createUniqueId } from '../../lib/unique-id.ts';
 import type { AnyNodeDefinition } from '../../parse/model/NodeDefinition.ts';
+import type { Attribute } from '../Attribute.ts';
 import type { PrimaryInstance } from '../PrimaryInstance.ts';
 import type { Root } from '../Root.ts';
 import type { AnyChildNode, AnyNode, AnyParentNode } from '../hierarchy.ts';
@@ -51,6 +53,7 @@ export interface InstanceNodeStateSpec<Value = never> {
 	readonly label: Accessor<TextRange<'label'> | null> | null;
 	readonly hint: Accessor<TextRange<'hint'> | null> | null;
 	readonly children: Accessor<readonly FormNodeID[]> | null;
+	readonly attributes: Accessor<readonly Attribute[]> | null;
 	readonly valueOptions: InstanceNodeValueOptionsStateSpec;
 	readonly value: Signal<Value> | SimpleAtomicState<Value> | null;
 }
@@ -191,7 +194,7 @@ export abstract class InstanceNode<
 	constructor(
 		readonly instanceConfig: InstanceConfig,
 		readonly parent: Parent,
-		readonly instanceNode: StaticDocument | StaticElement | null,
+		readonly instanceNode: StaticAttribute | StaticDocument | StaticElement | null,
 		readonly definition: Definition,
 		options?: InstanceNodeOptions
 	) {
@@ -237,13 +240,13 @@ export abstract class InstanceNode<
 	 * (though for those nodes it will always be empty). This affords consistency
 	 * and efficiency of interface for those internal uses.
 	 */
-	abstract getChildren(this: AnyInstanceNode): readonly AnyChildNode[];
+	abstract getChildren(this: AnyInstanceNode): ReadonlyArray<Exclude<AnyChildNode, Attribute>>;
 
 	// XFormsXPathNode
 	/**
 	 * @todo Values as text nodes(?)
 	 */
-	getXPathChildNodes(): readonly AnyChildNode[] {
+	getXPathChildNodes(): ReadonlyArray<Exclude<AnyChildNode, Attribute>> {
 		return (this as AnyInstanceNode).getChildren().flatMap((child) => {
 			switch (child.nodeType) {
 				case 'repeat-range:controlled':

package/src/instance/abstract/ValueNode.ts

@@ -36,6 +36,7 @@ export type ValueNodeDefinition<V extends ValueType> = LeafNodeDefinition<V>;
 
 export interface ValueNodeStateSpec<RuntimeValue> extends DescendantNodeStateSpec<RuntimeValue> {
 	readonly children: null;
+	readonly attributes: null;
 	readonly value: SimpleAtomicState<RuntimeValue>;
 	readonly instanceValue: Accessor<string>;
 }

package/src/instance/attachments/buildAttributes.ts

@@ -0,0 +1,8 @@
+import { Attribute } from '../Attribute';
+import type { AnyParentNode } from '../hierarchy';
+
+export function buildAttributes(parent: AnyParentNode): Attribute[] {
+	return Array.from(parent.definition.attributes.values()).map((attributeDefinition) => {
+		return new Attribute(parent, attributeDefinition, attributeDefinition.template);
+	});
+}

package/src/instance/hierarchy.ts

@@ -1,3 +1,4 @@
+import type { Attribute } from './Attribute.ts';
 import type { Group } from './Group.ts';
 import type { AnyInputControl } from './InputControl.ts';
 import type { AnyModelValue } from './ModelValue.ts';
@@ -62,7 +63,8 @@ export type AnyChildNode =
 	| RankControl
 	| SelectControl
 	| TriggerControl
-	| UploadControl;
+	| UploadControl
+	| Attribute;
 
 // prettier-ignore
 export type GeneralChildNode =

package/src/instance/internal-api/AttributeContext.ts

@@ -0,0 +1,34 @@
+import type { FormInstanceInitializationMode } from '../../client/index.ts';
+import type { StaticAttribute } from '../../integration/xpath/static-dom/StaticAttribute.ts';
+import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
+import type { BindComputationExpression } from '../../parse/expression/BindComputationExpression.ts';
+import type { AnyBindPreloadDefinition } from '../../parse/model/BindPreloadDefinition.ts';
+import type { EvaluationContext } from './EvaluationContext.ts';
+
+export interface InstanceAttributeContextDocument {
+	readonly initializationMode: FormInstanceInitializationMode;
+}
+
+export type DecodeInstanceValue = (value: string) => string;
+
+interface InstanceAttributeContextDefinitionBind {
+	readonly preload: AnyBindPreloadDefinition | null;
+	readonly calculate: BindComputationExpression<'calculate'> | null;
+	readonly readonly: BindComputationExpression<'readonly'>;
+}
+
+export interface InstanceAttributeContextDefinition {
+	readonly bind: InstanceAttributeContextDefinitionBind;
+	readonly template: StaticAttribute;
+}
+
+export interface AttributeContext extends EvaluationContext {
+	readonly scope: ReactiveScope;
+	readonly rootDocument: InstanceAttributeContextDocument;
+	readonly definition: InstanceAttributeContextDefinition;
+	readonly instanceNode: StaticAttribute;
+	readonly decodeInstanceValue: DecodeInstanceValue;
+
+	isReadonly(): boolean;
+	isRelevant(): boolean;
+}

package/src/instance/internal-api/serialization/ClientReactiveSerializableAttributeNode.ts

@@ -0,0 +1,19 @@
+import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
+import type { QualifiedName } from '../../../lib/names/QualifiedName.ts';
+
+export type SerializedInstanceValue = string;
+
+interface ClientReactiveSerializableAttributeNodeCurrentState {
+	get relevant(): boolean;
+	get instanceValue(): SerializedInstanceValue;
+}
+
+interface ClientReactiveSerializableAttributeNodeDefinition {
+	readonly qualifiedName: QualifiedName;
+}
+
+export interface ClientReactiveSerializableAttributeNode {
+	readonly definition: ClientReactiveSerializableAttributeNodeDefinition;
+	readonly currentState: ClientReactiveSerializableAttributeNodeCurrentState;
+	readonly instanceState: InstanceState;
+}

package/src/instance/internal-api/serialization/ClientReactiveSerializableParentNode.ts

@@ -1,5 +1,6 @@
 import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
 import type { QualifiedName } from '../../../lib/names/QualifiedName.ts';
+import type { Attribute } from '../../Attribute.ts';
 
 export interface ClientReactiveSerializableChildNode {
 	readonly instanceState: InstanceState;
@@ -10,6 +11,7 @@ export interface ClientReactiveSerializableParentNodeCurrentState<
 > {
 	get relevant(): boolean;
 	get children(): readonly Child[];
+	get attributes(): readonly Attribute[];
 }
 
 export interface ClientReactiveSerializableParentNodeDefinition {

package/src/instance/internal-api/serialization/ClientReactiveSerializableTemplatedNode.ts

@@ -1,5 +1,5 @@
-import type { TemplatedNodeAttributeSerializationError } from '../../../error/TemplatedNodeAttributeSerializationError.ts';
 import type { StaticElement } from '../../../integration/xpath/static-dom/StaticElement.ts';
+import type { Attribute } from '../../Attribute.ts';
 import type { GeneralChildNode } from '../../hierarchy.ts';
 import type {
 	ClientReactiveSerializableParentNode,
@@ -9,8 +9,7 @@ import type {
 
 export interface ClientReactiveSerializableTemplatedNodeCurrentState
 	extends ClientReactiveSerializableParentNodeCurrentState<GeneralChildNode> {
-	/** @see {@link TemplatedNodeAttributeSerializationError} */
-	get attributes(): unknown;
+	get attributes(): readonly Attribute[];
 }
 
 export interface ClientReactiveSerializableTemplatedNodeDefinition

package/src/instance/repeat/BaseRepeatRange.ts

@@ -17,6 +17,10 @@ import type {
 import { XFORMS_XPATH_NODE_RANGE_KIND } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
 import type { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
 import { createNodeRangeInstanceState } from '../../lib/client-reactivity/instance-state/createNodeRangeInstanceState.ts';
+import {
+	createAttributeState,
+	type AttributeState,
+} from '../../lib/reactivity/createAttributeState.ts';
 import type { ChildrenState } from '../../lib/reactivity/createChildrenState.ts';
 import { createChildrenState } from '../../lib/reactivity/createChildrenState.ts';
 import type { MaterializedChildren } from '../../lib/reactivity/materializeCurrentStateChildren.ts';
@@ -32,6 +36,7 @@ import type {
 	DescendantNodeSharedStateSpec,
 } from '../abstract/DescendantNode.ts';
 import { DescendantNode } from '../abstract/DescendantNode.ts';
+import type { Attribute } from '../Attribute.ts';
 import type { GeneralParentNode, RepeatRange } from '../hierarchy.ts';
 import type { EvaluationContext } from '../internal-api/EvaluationContext.ts';
 import type { ClientReactiveSerializableParentNode } from '../internal-api/serialization/ClientReactiveSerializableParentNode.ts';
@@ -41,6 +46,7 @@ interface RepeatRangeStateSpec extends DescendantNodeSharedStateSpec {
 	readonly hint: null;
 	readonly label: Accessor<TextRange<'label'> | null>;
 	readonly children: Accessor<readonly FormNodeID[]>;
+	readonly attributes: Accessor<readonly Attribute[]>;
 	readonly valueOptions: null;
 	readonly value: null;
 }
@@ -60,6 +66,7 @@ export abstract class BaseRepeatRange<Definition extends AnyRepeatDefinition>
 		ClientReactiveSerializableParentNode<RepeatInstance>
 {
 	protected readonly childrenState: ChildrenState<RepeatInstance>;
+	protected readonly attributeState: AttributeState;
 
 	/**
 	 * A repeat range doesn't have a corresponding primary instance element of its
@@ -156,8 +163,10 @@ export abstract class BaseRepeatRange<Definition extends AnyRepeatDefinition>
 		const repeatRange = this as AnyDescendantNode as RepeatRange;
 
 		const childrenState = createChildrenState<RepeatRange, RepeatInstance>(repeatRange);
+		const attributeState = createAttributeState(this.scope);
 
 		this.childrenState = childrenState;
+		this.attributeState = attributeState;
 
 		const state = createSharedNodeState(
 			this.scope,
@@ -170,6 +179,7 @@ export abstract class BaseRepeatRange<Definition extends AnyRepeatDefinition>
 				label: createNodeLabel(this, definition),
 				hint: null,
 				children: childrenState.childIds,
+				attributes: attributeState.getAttributes,
 				valueOptions: null,
 				value: null,
 			},
@@ -260,4 +270,8 @@ export abstract class BaseRepeatRange<Definition extends AnyRepeatDefinition>
 	getChildren(): readonly RepeatInstance[] {
 		return this.childrenState.getChildren();
 	}
+
+	getAttributes(): readonly Attribute[] {
+		return this.attributeState.getAttributes();
+	}
 }

package/src/instance/repeat/RepeatInstance.ts

@@ -10,10 +10,13 @@ import type {
 import type { InstanceState } from '../../client/serialization/InstanceState.ts';
 import type { TextRange } from '../../client/TextRange.ts';
 import type { AncestorNodeValidationState } from '../../client/validation.ts';
-import type { TemplatedNodeAttributeSerializationError } from '../../error/TemplatedNodeAttributeSerializationError.ts';
 import type { XFormsXPathElement } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
 import type { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
 import { createTemplatedNodeInstanceState } from '../../lib/client-reactivity/instance-state/createTemplatedNodeInstanceState.ts';
+import {
+	createAttributeState,
+	type AttributeState,
+} from '../../lib/reactivity/createAttributeState.ts';
 import type { ChildrenState } from '../../lib/reactivity/createChildrenState.ts';
 import { createChildrenState } from '../../lib/reactivity/createChildrenState.ts';
 import type { MaterializedChildren } from '../../lib/reactivity/materializeCurrentStateChildren.ts';
@@ -26,6 +29,7 @@ import { createNodeLabel } from '../../lib/reactivity/text/createNodeLabel.ts';
 import { createAggregatedViolations } from '../../lib/reactivity/validation/createAggregatedViolations.ts';
 import type { DescendantNodeSharedStateSpec } from '../abstract/DescendantNode.ts';
 import { DescendantNode } from '../abstract/DescendantNode.ts';
+import type { Attribute } from '../Attribute.ts';
 import { buildChildren } from '../children/buildChildren.ts';
 import type { GeneralChildNode, RepeatRange } from '../hierarchy.ts';
 import type { EvaluationContext } from '../internal-api/EvaluationContext.ts';
@@ -35,9 +39,7 @@ interface RepeatInstanceStateSpec extends DescendantNodeSharedStateSpec {
 	readonly label: Accessor<TextRange<'label'> | null>;
 	readonly hint: null;
 
-	/** @see {@link TemplatedNodeAttributeSerializationError} */
-	readonly attributes: null;
-
+	readonly attributes: Accessor<readonly Attribute[]>;
 	readonly children: Accessor<readonly FormNodeID[]>;
 	readonly valueOptions: null;
 	readonly value: null;
@@ -61,6 +63,7 @@ export class RepeatInstance
 		ClientReactiveSerializableTemplatedNode
 {
 	private readonly childrenState: ChildrenState<GeneralChildNode>;
+	private readonly attributeState: AttributeState;
 	private readonly currentIndex: Accessor<number>;
 
 	override readonly [XPathNodeKindKey] = 'element';
@@ -132,8 +135,10 @@ export class RepeatInstance
 		this.appearances = definition.bodyElement.appearances;
 
 		const childrenState = createChildrenState<RepeatInstance, GeneralChildNode>(this);
+		const attributeState = createAttributeState(this.scope);
 
 		this.childrenState = childrenState;
+		this.attributeState = attributeState;
 		this.currentIndex = currentIndex;
 
 		const state = createSharedNodeState(
@@ -147,7 +152,7 @@ export class RepeatInstance
 				// TODO: only-child <group><label>
 				label: createNodeLabel(this, definition),
 				hint: null,
-				attributes: null,
+				attributes: attributeState.getAttributes,
 				children: childrenState.childIds,
 				valueOptions: null,
 				value: null,
@@ -192,4 +197,8 @@ export class RepeatInstance
 	getChildren(): readonly GeneralChildNode[] {
 		return this.childrenState.getChildren();
 	}
+
+	getAttributes(): readonly Attribute[] {
+		return this.attributeState.getAttributes();
+	}
 }

package/src/integration/xpath/adapter/XFormsXPathNode.ts

@@ -97,7 +97,8 @@ export type XFormsXPathDescendantNodeKind =
 	| XFormsXPathNodeRangeKind
 	| XPathElementKind
 	| XPathTextKind
-	| XPathCommentKind;
+	| XPathCommentKind
+	| XPathAttributeKind;
 
 export interface XFormsXPathDescendantNode extends XFormsXPathNode {
 	readonly [XPathNodeKindKey]: XFormsXPathDescendantNodeKind;
@@ -109,6 +110,7 @@ export type XFormsXPathPrimaryInstanceNodeKind =
 	| XPathDocumentKind
 	| XFormsXPathNodeRangeKind
 	| XPathElementKind
+	| XPathAttributeKind
 	| XPathTextKind;
 
 export interface XFormsXPathPrimaryInstanceNode extends XFormsXPathNode {

package/src/lib/client-reactivity/instance-state/createAttributeNodeInstanceState.ts

@@ -0,0 +1,16 @@
+import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
+import type { ClientReactiveSerializableAttributeNode } from '../../../instance/internal-api/serialization/ClientReactiveSerializableAttributeNode.ts';
+import { escapeXMLText, serializeAttributeXML } from '../../xml-serialization.ts';
+
+export const createAttributeNodeInstanceState = (
+	node: ClientReactiveSerializableAttributeNode
+): InstanceState => {
+	const { qualifiedName } = node.definition;
+
+	return {
+		get instanceXML() {
+			const xmlValue = escapeXMLText(node.currentState.instanceValue, true);
+			return serializeAttributeXML(qualifiedName, xmlValue);
+		},
+	};
+};

package/src/lib/client-reactivity/instance-state/createParentNodeInstanceState.ts

@@ -12,11 +12,11 @@ export const createParentNodeInstanceState = (
 				return '';
 			}
 
-			const serializedChildren = node.currentState.children.map((child) => {
-				return child.instanceState.instanceXML;
-			});
-
-			return serializeParentElementXML(node.definition.qualifiedName, serializedChildren);
+			return serializeParentElementXML(
+				node.definition.qualifiedName,
+				node.currentState.children,
+				node.currentState.attributes
+			);
 		},
 	};
 };

package/src/lib/client-reactivity/instance-state/createRootInstanceState.ts

@@ -5,15 +5,12 @@ import { serializeParentElementXML } from '../../xml-serialization.ts';
 export const createRootInstanceState = (node: Root): InstanceState => {
 	return {
 		get instanceXML() {
-			const { namespaceDeclarations, attributes } = node.definition;
-			const serializedChildren = node.currentState.children.map((child) => {
-				return child.instanceState.instanceXML;
-			});
-
-			return serializeParentElementXML(node.definition.qualifiedName, serializedChildren, {
-				namespaceDeclarations,
-				attributes: Array.from(attributes.values()),
-			});
+			return serializeParentElementXML(
+				node.definition.qualifiedName,
+				node.currentState.children,
+				node.currentState.attributes,
+				node.definition.namespaceDeclarations
+			);
 		},
 	};
 };

package/src/lib/client-reactivity/instance-state/createTemplatedNodeInstanceState.ts

@@ -1,11 +1,7 @@
 import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
-import { TemplatedNodeAttributeSerializationError } from '../../../error/TemplatedNodeAttributeSerializationError.ts';
 import type { ClientReactiveSerializableTemplatedNode } from '../../../instance/internal-api/serialization/ClientReactiveSerializableTemplatedNode.ts';
 import { serializeParentElementXML } from '../../xml-serialization.ts';
 
-/**
- * @see {@link TemplatedNodeAttributeSerializationError}
- */
 export const createTemplatedNodeInstanceState = (
 	node: ClientReactiveSerializableTemplatedNode
 ): InstanceState => {
@@ -15,17 +11,11 @@ export const createTemplatedNodeInstanceState = (
 				return '';
 			}
 
-			const serializedChildren = node.currentState.children.map((child) => {
-				return child.instanceState.instanceXML;
-			});
-
-			const { attributes } = node.currentState;
-
-			if (attributes != null) {
-				throw new TemplatedNodeAttributeSerializationError();
-			}
-
-			return serializeParentElementXML(node.definition.qualifiedName, serializedChildren);
+			return serializeParentElementXML(
+				node.definition.qualifiedName,
+				node.currentState.children,
+				node.currentState.attributes
+			);
 		},
 	};
 };

package/src/lib/names/NamespaceDeclarationMap.ts

@@ -11,7 +11,7 @@ type NamedNodeDefinitionMap = ReadonlyMap<QualifiedName, NamedNodeDefinition>;
 export interface NamedSubtreeDefinition extends NamedNodeDefinition {
 	readonly namespaceDeclarations: NamespaceDeclarationMap;
 	readonly parent: NamedSubtreeDefinition | null;
-	readonly attributes?: NamedNodeDefinitionMap;
+	readonly attributes: NamedNodeDefinitionMap | null;
 }
 
 /**

package/src/lib/reactivity/createAttributeState.ts

@@ -0,0 +1,51 @@
+import type { Accessor, Setter, Signal } from 'solid-js';
+import { createSignal } from 'solid-js';
+import type { Attribute } from '../../instance/Attribute.ts';
+import type { ReactiveScope } from './scope.ts';
+
+export interface AttributeState {
+	readonly attributes: Signal<readonly Attribute[]>;
+	readonly getAttributes: Accessor<readonly Attribute[]>;
+	readonly setAttributes: Setter<readonly Attribute[]>;
+}
+
+/**
+ * Creates attributes state suitable for all node types
+ *
+ * The produced {@link AttributeState.attributes} (and its get/set convenience
+ * methods) signal is intended to be used to store the engine's attribute state,
+ * and update that state when appropriate.
+ */
+export const createAttributeState = (scope: ReactiveScope): AttributeState => {
+	return scope.runTask(() => {
+		const baseState = createSignal<readonly Attribute[]>([]);
+		const [getAttributes, baseSetAttributes] = baseState;
+
+		type AttributeSetterCallback = (prev: readonly Attribute[]) => readonly Attribute[];
+		type AttributeOrSetterCallback = AttributeSetterCallback | readonly Attribute[];
+
+		const setAttributes: Setter<readonly Attribute[]> = (
+			valueOrSetterCallback: AttributeOrSetterCallback
+		) => {
+			let setterCallback: AttributeSetterCallback;
+
+			if (typeof valueOrSetterCallback === 'function') {
+				setterCallback = valueOrSetterCallback;
+			} else {
+				setterCallback = (_) => valueOrSetterCallback;
+			}
+
+			return baseSetAttributes((prev) => {
+				return setterCallback(prev);
+			});
+		};
+
+		const attributes: Signal<readonly Attribute[]> = [getAttributes, setAttributes];
+
+		return {
+			attributes,
+			getAttributes,
+			setAttributes,
+		};
+	});
+};

package/src/lib/reactivity/createAttributeValueState.ts

@@ -0,0 +1,189 @@
+import type { Signal } from 'solid-js';
+import { createComputed, createMemo, createSignal, untrack } from 'solid-js';
+import type { AttributeContext } from '../../instance/internal-api/AttributeContext.ts';
+import type { BindComputationExpression } from '../../parse/expression/BindComputationExpression.ts';
+import { createComputedExpression } from './createComputedExpression.ts';
+import type { SimpleAtomicState, SimpleAtomicStateSetter } from './types.ts';
+
+const isInstanceFirstLoad = (context: AttributeContext) => {
+	return context.rootDocument.initializationMode === 'create';
+};
+
+/**
+ * Special case, does not correspond to any event.
+ *
+ * @see {@link shouldPreloadUID}
+ */
+const isEditInitialLoad = (context: AttributeContext) => {
+	return context.rootDocument.initializationMode === 'edit';
+};
+
+const getInitialValue = (context: AttributeContext): string => {
+	const sourceNode = context.instanceNode ?? context.definition.template;
+
+	return context.decodeInstanceValue(sourceNode.value);
+};
+
+type BaseValueState = Signal<string>;
+
+type RelevantValueState = SimpleAtomicState<string>;
+
+/**
+ * Wraps {@link baseValueState} in a signal-like interface which:
+ *
+ * - produces a blank value for nodes ({@link context}) in a non-relevant state
+ * - persists, and restores, the most recent non-blank value state when a
+ *   node/context's relevance is restored
+ */
+const createRelevantValueState = (
+	context: AttributeContext,
+	baseValueState: BaseValueState
+): RelevantValueState => {
+	return context.scope.runTask(() => {
+		const [getRelevantValue, setValue] = baseValueState;
+
+		const getValue = createMemo(() => {
+			if (context.isRelevant()) {
+				return getRelevantValue();
+			}
+
+			return '';
+		});
+
+		return [getValue, setValue];
+	});
+};
+
+/**
+ * For fields with a `readonly` bind expression, prevent downstream
+ * (client/user) writes when the field is in a `readonly` state.
+ */
+const guardDownstreamReadonlyWrites = (
+	context: AttributeContext,
+	baseState: SimpleAtomicState<string>
+): SimpleAtomicState<string> => {
+	const { readonly } = context.definition.bind;
+
+	if (readonly.isDefaultExpression) {
+		return baseState;
+	}
+
+	const [getValue, baseSetValue] = baseState;
+
+	const setValue: SimpleAtomicStateSetter<string> = (value) => {
+		if (context.isReadonly()) {
+			const reference = untrack(() => context.contextReference());
+
+			throw new Error(`Cannot write to readonly field: ${reference}`);
+		}
+
+		return baseSetValue(value);
+	};
+
+	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 It feels increasingly awkward to keep piling up preload stuff here, but it won't stay that way for long. In the meantime, this seems like the best way to express the cases where `preload="uid"` should be effective, i.e.:
+ *
+ * - When an instance is first loaded ({@link isInstanceFirstLoad})
+ * - When an instance is initially loaded for editing ({@link isEditInitialLoad})
+ */
+const shouldPreloadUID = (context: AttributeContext) => {
+	return isInstanceFirstLoad(context) || isEditInitialLoad(context);
+};
+
+/**
+ * @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: AttributeContext, valueState: RelevantValueState): void => {
+	const { preload } = context.definition.bind;
+
+	if (preload?.type !== 'uid' || !shouldPreloadUID(context)) {
+		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: AttributeContext,
+	setRelevantValue: SimpleAtomicStateSetter<string>,
+	calculateDefinition: BindComputationExpression<'calculate'>
+): void => {
+	context.scope.runTask(() => {
+		const calculate = createComputedExpression(context, calculateDefinition, {
+			defaultValue: '',
+		});
+
+		createComputed(() => {
+			if (context.isAttached() && context.isRelevant()) {
+				const calculated = calculate();
+				const value = context.decodeInstanceValue(calculated);
+
+				setRelevantValue(value);
+			}
+		});
+	});
+};
+
+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 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 const createAttributeValueState = (context: AttributeContext): InstanceValueState => {
+	return context.scope.runTask(() => {
+		const initialValue = getInitialValue(context);
+		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);
+
+		const { calculate } = context.definition.bind;
+
+		if (calculate != null) {
+			const [, setValue] = relevantValueState;
+
+			createCalculation(context, setValue, calculate);
+		}
+
+		return guardDownstreamReadonlyWrites(context, relevantValueState);
+	});
+};