@getodk/xforms-engine 0.1.0

package/dist/client/BaseNode.d.ts

@@ -0,0 +1,138 @@
+import type { AnyNodeDefinition } from '../model/NodeDefinition.ts';
+import type { InstanceNodeType } from './node-types.js';
+import type { TextRange } from './TextRange.ts';
+export interface BaseNodeState {
+    /**
+     * Location path reference to the node's primary instance state. This property
+     * may change if a node's position changes, e.g. when a repeat instance is
+     * removed. Its potential reactivity allows nodes to re-run computations which
+     * depend on the node's position itself, or when any other relative reference
+     * might target different nodes as a result of the positional change.
+     *
+     * @example
+     * /data/repeat[1]/foo
+     * /data/repeat[2]/foo
+     */
+    get reference(): string;
+    /**
+     * Note: a node's `readonly` state may become `true` by inheriting that state
+     * from one of its ancestors. Computing this inheritance is handled by the
+     * engine, but it may be of interest to clients.
+     *
+     * In the future, a more granular type might convey this detail more
+     * explicitly (at the expense of a more complex type). For now, a client can
+     * infer that inheritance by visiting the
+     * {@link BaseNode.parent | parent node}.
+     */
+    get readonly(): boolean;
+    /**
+     * Note: a node's `relevant` state may become `false` by inheriting that state
+     * from one of its ancestors. Computing this inheritance is handled by the
+     * engine, but it may be of interest to clients.
+     *
+     * In the future, a more granular type might convey this detail more
+     * explicitly (at the expense of a more complex type). For now, a client can
+     * infer that inheritance by visiting the
+     * {@link BaseNode.parent | parent node}.
+     */
+    get relevant(): boolean;
+    get required(): boolean;
+    /**
+     * Interfaces for nodes which cannot provide a label should override this to
+     * specify that the property will always be `null`.
+     */
+    get label(): TextRange<'label'> | null;
+    /**
+     * Interfaces for nodes which cannot provide a hint should override this to
+     * specify that the property will always be `null`.
+     */
+    get hint(): TextRange<'hint'> | null;
+    /**
+     * Each node's children (if it is a parent node) will be accessed on that
+     * node's state. While some node types will technically have static children,
+     * other nodes' children will be stateful (i.e. repeats). For a client, both
+     * cases are accessed the same way for consistency.
+     *
+     * Certain kinds of nodes are considered parent nodes: they may have child
+     * nodes. In some cases (presently, repeat ranges), children may be added or
+     * removed while a user is filling a form. As such, those children must be
+     * accessed as part of the node's
+     * {@link BaseNode.currentState | current state}. (In contrast, child nodes
+     * are never moved between different parents, so their
+     * {@link BaseNode.parent | parent} is static rather than part of their
+     * current state).
+     *
+     * A node is either:
+     *
+     * - Always a parent, in which case its `children` state should always produce
+     *   an array. When the parent node's children can be added or removed, an
+     *   empty array should be used to represent the absence of any children in
+     *   its current state.
+     * - Never a parent, in which case its `children` state should always produce
+     *   `null`. Such a node will instead have a {@link value}.
+     */
+    get children(): readonly BaseNode[] | null;
+    /**
+     * Certain kinds of nodes restrict their {@link value} to a specific set of
+     * valid values. Where they do, they will provide a collection (typically an
+     * array) of those values. This collection may be updated depending on other
+     * aspects of form state, which is why it is treated as a part of the node's
+     * state.
+     *
+     * Nodes which do not have this restriction (including nodes which cannot have
+     * a value at all) will always produce `valueOptions: null`.
+     */
+    get valueOptions(): unknown;
+    /**
+     * Certain kinds of nodes store a value state. Where they do, they will
+     * specify the type of the value directly.
+     *
+     * Parent nodes, i.e. nodes which can contain {@link children}, do not store a
+     * value state. For those nodes, their value state should always be `null`.
+     */
+    get value(): unknown;
+}
+type FormNodeID = string;
+/**
+ * Base interface for common/shared aspects of any node type.
+ */
+export interface BaseNode {
+    /**
+     * Specifies the node's general type. This can be useful for narrowing types,
+     * e.g. those of children.
+     */
+    readonly nodeType: InstanceNodeType;
+    /**
+     * Each node has a unique identifier. This identifier is stable throughout
+     * the lifetime of an active session filling a form.
+     */
+    readonly nodeId: FormNodeID;
+    /**
+     * Each node has a definition which specifies aspects of the node defined in
+     * the form. These aspects include (but are not limited to) the node's data
+     * type, its body presentation constraints (if any), its bound nodeset, and
+     * so on...
+     *
+     * @todo Interfaces for specific (non-base) node types should override this
+     * to specify the actual (concrete or union) type of their `definition`.
+     */
+    readonly definition: AnyNodeDefinition;
+    /**
+     * Each node links back to the node representing the root of the form.
+     *
+     * @todo Interfaces for all concrete node types should override this to
+     * specify the actual root node type.
+     */
+    readonly root: BaseNode;
+    /**
+     * Each node links back to its parent, if any. All nodes have a parent except
+     * the form's {@link root}.
+     */
+    readonly parent: BaseNode | null;
+    /**
+     * Each node provides a discrete object representing the stateful aspects of
+     * that node which will change over time. When a client provides a {@link OpaqueReactiveObjectFactory}
+     */
+    readonly currentState: BaseNodeState;
+}
+export {};

package/dist/client/EngineConfig.d.ts

@@ -0,0 +1,78 @@
+import type { OpaqueReactiveObjectFactory } from './OpaqueReactiveObjectFactory.ts';
+/**
+ * @todo this is currently a strict subset of the web standard `Response`. Is it
+ * sufficient? Ways it might not be:
+ *
+ * - No way to convey metadata about the resource
+ * - Ambiguous if a client supplies an alternative implementation which doesn't
+ *   exhaust the body on access
+ */
+export interface FetchResourceResponse {
+    readonly ok?: boolean;
+    readonly body?: ReadableStream<Uint8Array> | null;
+    readonly bodyUsed?: boolean;
+    readonly blob: () => Promise<Blob>;
+    readonly text: () => Promise<string>;
+}
+/**
+ * @todo this is a strict subset of the web standard `fetch` interface. It
+ * implicitly assumes that the engine itself will only ever issue `GET`-like
+ * requests. It also provides no further request-like semantics to the engine.
+ * This is presumed sufficient for now, but notably doesn't expose any notion of
+ * content negotiation (e.g. the ability to supply `Accept` headers).
+ *
+ * This also completely ignores any notion of mapping
+ * {@link https://getodk.github.io/xforms-spec/#uris | `jr:` URLs} to their
+ * actual resources (likely, but not necessarily, accessed at a corresponding
+ * HTTP URL).
+ */
+export type FetchResource = (resource: URL) => Promise<FetchResourceResponse>;
+/**
+ * Options provided by a client to specify certain aspects of engine runtime
+ * behavior. These options will generally be intended to facilitate cooperation
+ * where there is mixed responsibility between a client and the engine, or where
+ * the engine may provide sensible defaults which a client could be expected to
+ * override or augment.
+ */
+export interface EngineConfig {
+    /**
+     * A client may specify a generic function for constructing stateful objects.
+     * The only hard requirement of this function is that it accepts an **object**
+     * and returns an object of the same shape. The engine will use this function
+     * to initialize client-facing state, and will mutate properties of the object
+     * when their corresponding state is changed.
+     *
+     * A client may use this function to provide its own implementation of
+     * reactivity with semantics like those described above. The mechanism of
+     * reactivity, if any, is at the discretion of the client. It is expected
+     * that clients providing this function will use a reactive subscribe-on-read
+     * mechanism to handle state updates conveyed by the engine.
+     */
+    readonly stateFactory?: OpaqueReactiveObjectFactory;
+    /**
+     * A client may specify a generic function for retrieving resources referenced
+     * by a form, such as:
+     *
+     * - Form definitions themselves (if not provided directly to the engine by
+     *   the client)
+     * - External secondary instances
+     * - Media (images, audio, video, etc.)
+     *
+     * The function is expected to be a subset of the
+     * {@link https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API | Fetch API},
+     * performing `GET` requests for:
+     *
+     * - Text resources (e.g. XML, CSV, JSON/GeoJSON)
+     * - Binary resources (e.g. media)
+     * - Optionally streamed binary data of either (e.g. for optimized
+     *   presentation of audio/video)
+     *
+     * If provided by a client, this function will be used by the engine to
+     * retrieve any such resource, as required for engine functionality. If
+     * absent, the engine will use the native `fetch` function (if available, a
+     * polyfill otherwise). Clients may use this function to provide resources
+     * from sources other than the network, (or even in a test client to provide
+     * e.g. resources from test fixtures).
+     */
+    readonly fetchResource?: FetchResource;
+}

package/dist/client/FormLanguage.d.ts

@@ -0,0 +1,63 @@
+interface BaseFormLanguage {
+    /**
+     * @see {@link ActiveLanguage} for details.
+     */
+    readonly isSyntheticDefault?: true;
+    /**
+     * As derived directly from the form's
+     * {@link https://getodk.github.io/xforms-spec/#languages | `itext` translations}.
+     */
+    readonly language: string;
+    /**
+     * Where possible, a form's languages may detect the standardized locale
+     * corresponding to the language as specified in the form.
+     */
+    readonly locale?: Intl.Locale;
+}
+/**
+ * @see {@link ActiveLanguage} for details.
+ */
+export interface SyntheticDefaultLanguage extends BaseFormLanguage {
+    readonly isSyntheticDefault: true;
+    readonly language: '';
+}
+/**
+ * A language available for a given form, as defined by that form's {@link https://getodk.github.io/xforms-spec/#languages | `itext` translations}.
+ *
+ * @see {@link ActiveLanguage} for additional details.
+ */
+export interface FormLanguage extends BaseFormLanguage {
+    readonly isSyntheticDefault?: never;
+}
+/**
+ * A form with translations will always have one or more {@link FormLanguage}s,
+ * with the default chosen as described in the ODK XForms specification.
+ *
+ * A form that specifies no translations will always have a single
+ * {@link SyntheticDefaultLanguage}.
+ *
+ * No form will ever combine both types of language.
+ *
+ * This distinction is intended to avoid confusion about the **potential** state
+ * of a form's active language. A naive type to express the possibility, without
+ * a synthetic default, would be something like `FormLanguage | null`, which
+ * would seem to suggest to a client that a form may **only sometimes** have an
+ * active language—for instance, that there might be a way for a client to turn
+ * translation off and on.
+ *
+ * By ensuring there is always _some active language value_, and by expressing
+ * the {@link FormLanguages} type to correspond to each of the possibilities
+ * discussed above, it's hoped that the set of potential translation states a
+ * client might encounter/establish are more clear.
+ */
+export type ActiveLanguage = FormLanguage | SyntheticDefaultLanguage;
+/**
+ * A form may either have:
+ *
+ * - one or more available {@link FormLanguage}s, as defined by the form
+ * - exactly one {@link SyntheticDefaultLanguage}
+ *
+ * @see {@link ActiveLanguage} for additional details.
+ */
+export type FormLanguages = readonly [FormLanguage, ...FormLanguage[]] | readonly [SyntheticDefaultLanguage];
+export {};

package/dist/client/GroupNode.d.ts

@@ -0,0 +1,24 @@
+import type { NonRepeatGroupElementDefinition } from '../body/BodyDefinition.ts';
+import type { SubtreeDefinition } from '../model/SubtreeDefinition.ts';
+import type { BaseNode, BaseNodeState } from './BaseNode.ts';
+import type { RootNode } from './RootNode.ts';
+import type { GeneralChildNode, GeneralParentNode } from './hierarchy.ts';
+export interface GroupNodeState extends BaseNodeState {
+    get hint(): null;
+    get children(): readonly GeneralChildNode[];
+    get valueOptions(): null;
+    get value(): null;
+}
+export interface GroupDefinition extends SubtreeDefinition {
+    readonly bodyElement: NonRepeatGroupElementDefinition;
+}
+/**
+ * A node corresponding to an XForms `<group>`.
+ */
+export interface GroupNode extends BaseNode {
+    readonly nodeType: 'group';
+    readonly definition: GroupDefinition;
+    readonly root: RootNode;
+    readonly parent: GeneralParentNode;
+    readonly currentState: GroupNodeState;
+}

package/dist/client/OpaqueReactiveObjectFactory.d.ts

@@ -0,0 +1,70 @@
+interface BaseOpaqueReactiveObjectFactory<in out Input extends object = object> {
+    <T extends Input>(object: T): T;
+    <T extends object>(object: T): T;
+}
+/**
+ * A client-provided reactivity factory. We assume little about the mechanism
+ * of reactivity a client provides (and a client may opt to provide no reactive
+ * mechanism at all, if it will consume state changes by other means). From an
+ * API perspective, the expectation is:
+ *
+ * - The factory accepts a single argument, which **MUST** be an object.
+ *   Reactive primitive values are unsupported by this interface.
+ * - The factory **MUST** return an object of the same shape (i.e. it must
+ *   have the same property key/value pairs).
+ * - The factory's return object **MUST** be mutable by the web-forms engine.
+ * - The web-forms engine **WILL** propagate changes to state as they occur,
+ *   by mutating properties of the object corresponding to those aspects of
+ *   state.
+ * - The client **MAY** read any property of the factory's returned object.
+ * - Because the client's reactivity mechanism (if any) is unknown, it is
+ *   **ASSUMED** that the engine's mutations are observable by the client,
+ *   and that the client has a defined means to subscribe to those mutations.
+ *   It is **IMPLIED** (but **NOT REQUIRED**) that the typical reactive client
+ *   will subscribe to mutations by reading the pertinent properties of the
+ *   reactive object in a reactive context appropriate for that client.
+ * - In common usage, the engine **MAY** convey computed getter property types
+ *   back to the client, to indicate that certain aspects the engine mutates
+ *   are read-only to the client (even if they are mutable by the engine).
+ *
+ * Real world examples of reactive implementations include:
+ *
+ * - {@link https://vuejs.org/api/reactivity-core.html#reactive | `reactive` (Vue)}
+ * - {@link https://docs.solidjs.com/reference/store-utilities/create-mutable | `createMutable` (Solid)}
+ * - {@link DefineMutableObject | our internal `mutable` test helper}
+ *
+ * Each of these implementations are targeted as part of our effort to ensure
+ * the `xforms-engine` is agnostic to a client's framework and/or implementation
+ * of state.
+ *
+ * @example
+ *
+ * ```ts
+ * declare const clientFactory: OpaqueReactiveObjectFactory;
+ *
+ * interface ClientFoo {
+ *   get bar(): string;
+ * }
+ *
+ * interface MutableFoo {
+ *   bar: string;
+ * }
+ *
+ * // State internally updated by engine
+ * let mutableFoo = clientFactory<MutableFoo>({ bar: 'bat' });
+ *
+ * // Same state, consumed by the client as computed but read-only
+ * let clientFoo: ClientFoo = engineFoo;
+ *
+ * // Client: subscribe to mutations by the engine
+ * reactiveContext(() => {
+ *   // Implied client subscription to `clientFoo.bar` on property access
+ *   doSomethingWith(clientFoo.bar);
+ * });
+ *
+ * // Engine: mutate values to convey state changes to subscribed client
+ * engineFoo.bar = 'quux';
+ * ```
+ */
+export type OpaqueReactiveObjectFactory<Input extends object = object> = BaseOpaqueReactiveObjectFactory<Input> & ((object: object) => unknown);
+export {};

package/dist/client/RepeatInstanceNode.d.ts

@@ -0,0 +1,28 @@
+import type { RepeatInstanceDefinition } from '../model/RepeatInstanceDefinition.ts';
+import type { RepeatTemplateDefinition } from '../model/RepeatTemplateDefinition.ts';
+import type { BaseNode, BaseNodeState } from './BaseNode.ts';
+import type { RepeatRangeNode } from './RepeatRangeNode.ts';
+import type { RootNode } from './RootNode.ts';
+import type { GeneralChildNode } from './hierarchy.ts';
+export interface RepeatInstanceNodeState extends BaseNodeState {
+    get hint(): null;
+    get children(): readonly GeneralChildNode[];
+    get valueOptions(): null;
+    get value(): null;
+}
+export type RepeatDefinition = RepeatInstanceDefinition | RepeatTemplateDefinition;
+export interface RepeatInstanceNode extends BaseNode {
+    readonly nodeType: 'repeat-instance';
+    readonly definition: RepeatDefinition;
+    readonly root: RootNode;
+    /**
+     * A repeat instance may only be a child of a {@link RepeatRangeNode}.
+     *
+     * Note: the web-forms engine's representation of this structure differs from
+     * the underlying XForms specification's primary instance structure.
+     *
+     * @see {@link RepeatRangeNode} for additional detail.
+     */
+    readonly parent: RepeatRangeNode;
+    readonly currentState: RepeatInstanceNodeState;
+}

package/dist/client/RepeatRangeNode.d.ts

@@ -0,0 +1,94 @@
+import type { RepeatSequenceDefinition } from '../model/RepeatSequenceDefinition.ts';
+import type { BaseNode, BaseNodeState } from './BaseNode.ts';
+import type { RepeatInstanceNode } from './RepeatInstanceNode.ts';
+import type { RootNode } from './RootNode.ts';
+import type { TextRange } from './TextRange.ts';
+import type { GeneralParentNode } from './hierarchy.ts';
+export interface RepeatRangeNodeState extends BaseNodeState {
+    get hint(): null;
+    get label(): TextRange<'label'> | null;
+    /**
+     * A repeat range's children may only be {@link RepeatInstanceNode}s.
+     *
+     * Note: the web-forms engine's representation of this structure differs from
+     * the underlying XForms specification's primary instance structure.
+     *
+     * @see {@link RepeatRangeNode} for additional detail.
+     */
+    get children(): readonly RepeatInstanceNode[];
+    get valueOptions(): null;
+    get value(): null;
+}
+/**
+ * Represents a contiguous set of zero or more {@link RepeatInstanceNode}s
+ * (accessed by its
+ * {@link RepeatRangeNodeState.children | `currentState.children`}).
+ *
+ * This structure is modeled as a node, like any other, in the web-forms engine
+ * representation, which notably differs from the corresponding structure in the
+ * underlying ODK XForms specification's primary instance state.
+ *
+ * _Conceptually_, it more closely corresponds to the concept of a set of
+ * repeats as defined by a `<repeat>` element in the XForms body. Whereas its
+ * {@link RepeatInstanceNode} children, if any, correspond directly to the
+ * XForms primary instance's state.
+ *
+ * More precisely, clients should be advised that the presentation aspect of a
+ * `RepeatRangeNode` corresponds to a pair of
+ * {@link https://getodk.github.io/xforms-spec/#body-elements | `<group>` and `<repeat>` body elements}
+ * referencing the same nodeset. (Forms which define a repeat without a
+ * corresponding group are semantically equivalent to those with this
+ * group/repeat pair. The web-forms engine model simplifies this by producing
+ * the same runtime structure for either case.)
+ *
+ * @example
+ *
+ * To illustrate the structural divergence from the underlying XForms concepts,
+ * consider this (abridged) XForm definition:
+ *
+ * ```xml
+ * <!-- /h:html/h:head/model -->
+ * <instance>
+ *   <data>
+ *     <rep />
+ *   </data>
+ * </instance>
+ * <!-- /h:html/h:body -->
+ * <repeat nodeset="/data/rep" />
+ * ```
+ *
+ * The engine's representation maps to that structure roughly like:
+ *
+ * ```xml
+ * <!-- /h:html/h:head/model -->
+ * <instance>
+ *   <data>
+ *     <!-- RepeatRangeNode(/data/rep).currentState.children: [ -->
+ *       <!-- RepeatInstanceNode(/data/rep[1]): --> <rep />
+ *       <!-- RepeatInstanceNode(/data/rep[2]): --> <rep />
+ *       <!-- ... -->
+ *     <!-- ] -->
+ *   </data>
+ * </instance>
+ * <!-- /h:html/h:body -->
+ * <!-- RepeatRangeNode(/data/rep).definition: { ... -->
+ *   <group ref="/data/rep">
+ *     <repeat nodeset="/data/rep" />
+ *   </group>
+ * <!-- } -->
+ * ```
+ *
+ * Importantly, if the state of a given repeat range has no instances, no aspect
+ * of these repeats will be present in the underlying XForms primary instance
+ * state, but the web-forms engine's representations **retains a reference** to
+ * its {@link RepeatRangeNode}.
+ */
+export interface RepeatRangeNode extends BaseNode {
+    readonly nodeType: 'repeat-range';
+    readonly definition: RepeatSequenceDefinition;
+    readonly root: RootNode;
+    readonly parent: GeneralParentNode;
+    readonly currentState: RepeatRangeNodeState;
+    addInstances(afterIndex?: number, count?: number): RootNode;
+    removeInstances(startIndex: number, count?: number): RootNode;
+}

package/dist/client/RootNode.d.ts

@@ -0,0 +1,31 @@
+import type { RootDefinition } from '../model/RootDefinition.ts';
+import type { BaseNode, BaseNodeState } from './BaseNode.ts';
+import type { ActiveLanguage, FormLanguage, FormLanguages } from './FormLanguage.ts';
+import type { GeneralChildNode } from './hierarchy.ts';
+export interface RootNodeState extends BaseNodeState {
+    /**
+     * This, along with {@link RootNode.languages} is the most significant break
+       in consistency across node types' state and static properties. Exposing it
+       across all node types seems like a point of potential confusion, so this
+       particular divergence seems like the most reasonable compromise.
+     */
+    get activeLanguage(): ActiveLanguage;
+    get label(): null;
+    get hint(): null;
+    get children(): readonly GeneralChildNode[];
+    get valueOptions(): null;
+    get value(): null;
+}
+export interface RootNode extends BaseNode {
+    readonly nodeType: 'root';
+    readonly definition: RootDefinition;
+    readonly root: RootNode;
+    readonly parent: null;
+    readonly currentState: RootNodeState;
+    /**
+     * @todo as with {@link RootNodeState.activeLanguage}, this is the most
+     * significant break in consistency across node types.
+     */
+    readonly languages: FormLanguages;
+    setLanguage(language: FormLanguage): RootNode;
+}

package/dist/client/SelectNode.d.ts

@@ -0,0 +1,60 @@
+import type { AnySelectDefinition } from '../body/control/select/SelectDefinition.ts';
+import type { ValueNodeDefinition } from '../model/ValueNodeDefinition.ts';
+import type { BaseNode, BaseNodeState } from './BaseNode.ts';
+import type { RootNode } from './RootNode.ts';
+import type { TextRange } from './TextRange.ts';
+import type { GeneralParentNode } from './hierarchy.ts';
+export interface SelectItem {
+    get value(): string;
+    get label(): TextRange<'label'> | null;
+}
+export interface SelectNodeState extends BaseNodeState {
+    get children(): null;
+    /**
+     * @todo should {@link BaseNodeState} include this??
+     */
+    get valueOptions(): readonly SelectItem[];
+    /**
+     * This value is treated as set-like by the engine, where each
+     * {@link SelectItem.value | item's `value`} may occur once (at most), and:
+     *
+     * - Fields defined with an XForms `<select>` may contain multiple items
+     * - Fields defined with an XForms `<select1>` will always produce one item
+     *   (at most)
+     *
+     * @todo Maybe it makes more sense for the client interface to break these up!
+     * Should a `SelectNodeState` have this `value` type, whereas a hypothetical
+     * `Select1NodeState` would have `get value(): SelectItem | null`?
+     */
+    get value(): readonly SelectItem[];
+}
+export interface SelectDefinition extends ValueNodeDefinition {
+    readonly bodyElement: AnySelectDefinition;
+}
+export interface SelectNode extends BaseNode {
+    readonly nodeType: 'select';
+    readonly definition: SelectDefinition;
+    readonly root: RootNode;
+    readonly parent: GeneralParentNode;
+    readonly currentState: SelectNodeState;
+    /**
+     * For use by a client to update the selection of a select node where:
+     *
+     * - For fields defined with an XForms `<select>`, calling this method is
+     *   additive, i.e. it will include the item in its
+     *   {@link SelectNodeState.value}.
+     * - For fields defined with an XForms `<select1>`, calling this method will
+     *   replace the selection (if any).
+     *
+     * @todo @see {@link StringNode.setValue} re: write restrictions
+     * @todo @see {@link SelectNodeState.value} re: breaking up the types
+     */
+    select(item: SelectItem): RootNode;
+    /**
+     * For use by a client to remove an item from the node's
+     * {@link SelectNodeState.value}.
+     *
+     * @todo @see {@link StringNode.setValue} re: write restrictions
+     */
+    deselect(item: SelectItem): RootNode;
+}

package/dist/client/StringNode.d.ts

@@ -0,0 +1,41 @@
+import type { InputDefinition } from '../body/control/InputDefinition.ts';
+import type { ValueNodeDefinition } from '../model/ValueNodeDefinition.ts';
+import type { BaseNode, BaseNodeState } from './BaseNode.ts';
+import type { RootNode } from './RootNode.ts';
+import type { GeneralParentNode } from './hierarchy.ts';
+export interface StringNodeState extends BaseNodeState {
+    get children(): null;
+    get valueOptions(): null;
+    /**
+     * Reflects the current value of a {@link StringNode}. This value may be
+     * populated when a form is loaded, and it may be updated by certain
+     * computations defined by the form. It may also be updated by a client, using
+     * the {@link StringNode.setValue} method.
+     */
+    get value(): string;
+}
+export interface StringDefinition extends ValueNodeDefinition {
+    readonly bodyElement: InputDefinition | null;
+}
+/**
+ * A node which can be assigned a string/text value. A string node **MAY**
+ * correspond to form field defined as an XForms `<input>`, which a user-facing
+ * client would likely present for a user to fill. It may not correspond to an
+ * `<input>`, or necessarily have any presentational implications for a client
+ * (for instance if the node is bound to an XForms `calculate` expression).
+ */
+export interface StringNode extends BaseNode {
+    readonly nodeType: 'string';
+    readonly definition: StringDefinition;
+    readonly root: RootNode;
+    readonly parent: GeneralParentNode;
+    readonly currentState: StringNodeState;
+    /**
+     * For use by a client to update the value of a string node.
+     *
+     * @todo [how] should we express write restrictions to a client? E.g. what
+     * happens when a string node is readonly, and a client attempts to call this
+     * method?
+     */
+    setValue(value: string): RootNode;
+}