@getodk/xforms-engine 0.16.0 → 0.17.0

package/dist/client/AttributeNode.d.ts

@@ -1,14 +1,15 @@
 import { Root } from '../instance/Root.ts';
 import { AttributeDefinition } from '../parse/model/AttributeDefinition.ts';
+import { BaseNode, BaseNodeState } from './BaseNode.ts';
 import { InstanceState } from './serialization/InstanceState.ts';
-export interface AttributeNodeState {
+export interface AttributeNodeState extends BaseNodeState {
     get value(): string;
     get relevant(): boolean;
 }
 /**
  * Base interface for common/shared aspects of attributes.
  */
-export interface AttributeNode {
+export interface AttributeNode extends BaseNode {
     /**
      * Specifies the node's general type. This can be useful for narrowing types,
      * e.g. those of children.
@@ -25,7 +26,7 @@ export interface AttributeNode {
      * Each node links back to the node representing the root of the form.
      */
     readonly root: Root;
-    readonly owner: unknown;
+    readonly parent: unknown;
     /**
      * Each node provides a discrete object representing the stateful aspects of
      * that node which will change over time. This includes state which is either

package/dist/client/InputNode.d.ts

@@ -40,8 +40,8 @@ interface InputNodeOptionsByValueType {
     readonly time: null;
     readonly dateTime: null;
     readonly geopoint: GeoInputNodeOptions;
-    readonly geotrace: GeoInputNodeOptions;
-    readonly geoshape: GeoInputNodeOptions;
+    readonly geotrace: null;
+    readonly geoshape: null;
     readonly binary: null;
     readonly barcode: null;
     readonly intent: null;
@@ -72,13 +72,17 @@ export type IntInputValue = InputValue<'int'>;
 export type DecimalInputValue = InputValue<'decimal'>;
 export type DateInputValue = InputValue<'date'>;
 export type GeopointInputValue = InputValue<'geopoint'>;
+export type GeoshapeInputValue = InputValue<'geoshape'>;
+export type GeotraceInputValue = InputValue<'geotrace'>;
 export type StringInputNode = InputNode<'string'>;
 export type IntInputNode = InputNode<'int'>;
 export type DecimalInputNode = InputNode<'decimal'>;
 export type DateInputNode = InputNode<'date'>;
 export type GeopointInputNode = InputNode<'geopoint'>;
-type SupportedInputValueType = 'string' | 'int' | 'decimal' | 'date' | 'geopoint';
+export type GeoshapeInputNode = InputNode<'geoshape'>;
+export type GeotraceInputNode = InputNode<'geotrace'>;
+type SupportedInputValueType = 'string' | 'int' | 'decimal' | 'date' | 'geopoint' | 'geoshape' | 'geotrace';
 type TemporaryStringValueType = Exclude<ValueType, SupportedInputValueType>;
 export type TemporaryStringValueInputNode = InputNode<TemporaryStringValueType>;
-export type AnyInputNode = StringInputNode | IntInputNode | DecimalInputNode | DateInputNode | GeopointInputNode | TemporaryStringValueInputNode;
+export type AnyInputNode = StringInputNode | IntInputNode | DecimalInputNode | DateInputNode | GeopointInputNode | GeoshapeInputNode | GeotraceInputNode | TemporaryStringValueInputNode;
 export {};

package/dist/client/MarkdownNode.d.ts

@@ -2,15 +2,18 @@ export type Heading = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
 export type ElementName = Heading | 'a' | 'div' | 'em' | 'li' | 'ol' | 'p' | 'span' | 'strong' | 'u' | 'ul';
 export type MarkdownNode = ChildMarkdownNode | HtmlMarkdownNode | ParentMarkdownNode;
 export interface ParentMarkdownNode {
+    readonly id: string;
     readonly role: 'parent';
     readonly elementName: string;
     readonly children: MarkdownNode[];
 }
 export interface ChildMarkdownNode {
+    readonly id: string;
     readonly role: 'child';
     readonly value: string;
 }
 export interface HtmlMarkdownNode {
+    readonly id: string;
     readonly role: 'html';
     readonly unsafeHtml: string;
 }

package/dist/client/NoteNode.d.ts

@@ -59,13 +59,17 @@ export type IntNoteValue = NoteValue<'int'>;
 export type DecimalNoteValue = NoteValue<'decimal'>;
 export type DateNoteValue = NoteValue<'date'>;
 export type GeopointNoteValue = NoteValue<'geopoint'>;
+export type GeoshapeNoteValue = NoteValue<'geoshape'>;
+export type GeotraceNoteValue = NoteValue<'geotrace'>;
 export type StringNoteNode = NoteNode<'string'>;
 export type IntNoteNode = NoteNode<'int'>;
 export type DecimalNoteNode = NoteNode<'decimal'>;
 export type DateNoteNode = NoteNode<'date'>;
 export type GeopointNoteNode = NoteNode<'geopoint'>;
-type SupportedNoteValueType = 'string' | 'int' | 'decimal' | 'date' | 'geopoint';
+export type GeoshapeNoteNode = NoteNode<'geoshape'>;
+export type GeotraceNoteNode = NoteNode<'geotrace'>;
+type SupportedNoteValueType = 'string' | 'int' | 'decimal' | 'date' | 'geopoint' | 'geoshape' | 'geotrace';
 type TemporaryStringValueType = Exclude<ValueType, SupportedNoteValueType>;
 export type TemporaryStringValueNoteNode = NoteNode<TemporaryStringValueType>;
-export type AnyNoteNode = StringNoteNode | IntNoteNode | DecimalNoteNode | DateNoteNode | GeopointNoteNode | TemporaryStringValueNoteNode;
+export type AnyNoteNode = StringNoteNode | IntNoteNode | DecimalNoteNode | DateNoteNode | GeopointNoteNode | GeoshapeNoteNode | GeotraceNoteNode | TemporaryStringValueNoteNode;
 export {};

package/dist/client/form/FormInstanceConfig.d.ts

@@ -14,6 +14,9 @@ export interface PreloadProperties {
     readonly username?: string;
     readonly phoneNumber?: string;
 }
+export interface GeolocationProvider {
+    getLocation(): Promise<string>;
+}
 export interface FormInstanceConfig {
     /**
      * A client may specify a generic function for constructing stateful objects.
@@ -31,4 +34,5 @@ export interface FormInstanceConfig {
     readonly stateFactory?: OpaqueReactiveObjectFactory;
     readonly instanceAttachments?: InstanceAttachmentsConfig;
     readonly preloadProperties?: PreloadProperties;
+    readonly geolocationProvider?: GeolocationProvider;
 }

package/dist/client/form/LoadFormResult.d.ts

@@ -3,6 +3,7 @@ import { AnyFunction } from '../../../../common/types/helpers.js';
 import { LoadFormFailureError } from '../../error/LoadFormFailureError.ts';
 import { CreateFormInstance } from './CreateFormInstance.ts';
 import { EditFormInstance } from './EditFormInstance.ts';
+import { ResetFormInstance } from './ResetFormInstance.ts';
 import { RestoreFormInstance } from './RestoreFormInstance.ts';
 export type { LoadFormFailureError };
 export type FormResultStatus = 'success' | 'warning' | 'failure';
@@ -22,6 +23,7 @@ interface BaseLoadFormResult {
     readonly warnings: LoadFormWarnings | null;
     readonly error: LoadFormFailureError | null;
     readonly createInstance: FallibleLoadFormResultMethod<CreateFormInstance>;
+    readonly resetInstance: FallibleLoadFormResultMethod<ResetFormInstance>;
     readonly editInstance: FallibleLoadFormResultMethod<EditFormInstance>;
     readonly restoreInstance: FallibleLoadFormResultMethod<RestoreFormInstance>;
 }
@@ -30,6 +32,7 @@ export interface LoadFormSuccessResult extends BaseLoadFormResult {
     readonly warnings: null;
     readonly error: null;
     readonly createInstance: CreateFormInstance;
+    readonly resetInstance: ResetFormInstance;
     readonly editInstance: EditFormInstance;
     readonly restoreInstance: RestoreFormInstance;
 }
@@ -38,6 +41,7 @@ export interface LoadFormWarningResult extends BaseLoadFormResult {
     readonly warnings: LoadFormWarnings;
     readonly error: null;
     readonly createInstance: CreateFormInstance;
+    readonly resetInstance: ResetFormInstance;
     readonly editInstance: EditFormInstance;
     readonly restoreInstance: RestoreFormInstance;
 }
@@ -45,22 +49,9 @@ export interface LoadFormFailureResult extends BaseLoadFormResult {
     readonly status: 'failure';
     readonly warnings: LoadFormWarnings | null;
     readonly error: LoadFormFailureError;
-    /**
-     * @example A temporary demo integration was built during development of this
-     * interface.
-     *
-     * @see
-     * {@link https://github.com/getodk/web-forms/pull/345/commits/9ef36355d89dd1450d3a87c3a55506bb9b0fc414}
-     */
     readonly createInstance: FailedLoadFormResultMethod<CreateFormInstance>;
+    readonly resetInstance: FailedLoadFormResultMethod<ResetFormInstance>;
     readonly editInstance: FailedLoadFormResultMethod<EditFormInstance>;
-    /**
-     * @example A temporary demo integration was built during development of this
-     * interface.
-     *
-     * @see
-     * {@link https://github.com/getodk/web-forms/pull/345/commits/9ef36355d89dd1450d3a87c3a55506bb9b0fc414}
-     */
     readonly restoreInstance: FailedLoadFormResultMethod<RestoreFormInstance>;
 }
 export type InstantiableLoadFormResult = LoadFormSuccessResult | LoadFormWarningResult;

package/dist/client/form/ResetFormInstance.d.ts

@@ -0,0 +1,13 @@
+import { CreatedFormInstance } from './CreateFormInstance.ts';
+import { FormInstanceConfig } from './FormInstanceConfig.ts';
+/**
+ * @todo This is fallible! Client-facing interfaces will need to account for
+ * this. We've begun addressing fallibility _at the interface level_ in
+ * {@link LoadForm} (with {@link LoadFormResult}). We'll eventually have a more
+ * general interface pattern for this, and we'll apply it here as well. The baby
+ * step approach in {@link LoadFormResult} is impractical here due to
+ * engine-internal designs, and revising that is currently out of scope. As
+ * such, explicit interface-level documentation of fallibility is deferred here,
+ * on {@link RootNode} itself, and into any of its sub-interfaces.
+ */
+export type ResetFormInstance = (config?: FormInstanceConfig) => CreatedFormInstance;

package/dist/entrypoints/FormResult/BaseFormResult.d.ts

@@ -15,6 +15,7 @@ export declare abstract class BaseFormResult<Status extends FormResultStatus> {
     readonly warnings: BaseFormResultProperty<Status, 'warnings'>;
     readonly error: BaseFormResultProperty<Status, 'error'>;
     abstract readonly createInstance: BaseFormResultProperty<Status, 'createInstance'>;
+    abstract readonly resetInstance: BaseFormResultProperty<Status, 'resetInstance'>;
     abstract readonly editInstance: BaseFormResultProperty<Status, 'editInstance'>;
     abstract readonly restoreInstance: BaseFormResultProperty<Status, 'restoreInstance'>;
     constructor(options: BaseFormResultOptions<Status>);

package/dist/entrypoints/FormResult/BaseInstantiableFormResult.d.ts

@@ -1,5 +1,6 @@
 import { CreateFormInstance } from '../../client/form/CreateFormInstance.ts';
 import { EditFormInstance } from '../../client/form/EditFormInstance.ts';
+import { ResetFormInstance } from '../../client/form/ResetFormInstance.ts';
 import { RestoreFormInstance } from '../../client/form/RestoreFormInstance.ts';
 import { BasePrimaryInstanceOptions } from '../../instance/PrimaryInstance.ts';
 import { FormResource } from '../../instance/resource.ts';
@@ -17,6 +18,7 @@ export interface BaseInstantiableFormResultOptions<Status extends InstantiableFo
 }
 export declare abstract class BaseInstantiableFormResult<Status extends InstantiableFormResultStatus> extends BaseFormResult<Status> {
     readonly createInstance: CreateFormInstance;
+    readonly resetInstance: ResetFormInstance;
     readonly editInstance: EditFormInstance;
     readonly restoreInstance: RestoreFormInstance;
     constructor(options: BaseInstantiableFormResultOptions<Status>);

package/dist/entrypoints/FormResult/FormFailureResult.d.ts

@@ -1,6 +1,7 @@
 import { CreateFormInstance } from '../../client/form/CreateFormInstance.ts';
 import { EditFormInstance } from '../../client/form/EditFormInstance.ts';
 import { FailedLoadFormResultMethod, LoadFormFailureResult, LoadFormWarnings } from '../../client/form/LoadFormResult.ts';
+import { ResetFormInstance } from '../../client/form/ResetFormInstance.ts';
 import { RestoreFormInstance } from '../../client/form/RestoreFormInstance.ts';
 import { LoadFormFailureError } from '../../error/LoadFormFailureError.ts';
 import { BaseFormResult } from './BaseFormResult.ts';
@@ -10,6 +11,7 @@ interface FormFailureOptions {
 }
 export declare class FormFailureResult extends BaseFormResult<'failure'> implements LoadFormFailureResult {
     readonly createInstance: FailedLoadFormResultMethod<CreateFormInstance>;
+    readonly resetInstance: FailedLoadFormResultMethod<ResetFormInstance>;
     readonly editInstance: FailedLoadFormResultMethod<EditFormInstance>;
     readonly restoreInstance: FailedLoadFormResultMethod<RestoreFormInstance>;
     constructor(options: FormFailureOptions);

package/dist/entrypoints/createPotentiallyClientOwnedReactiveScope.d.ts

@@ -0,0 +1,19 @@
+import { ReactiveScope } from '../lib/reactivity/scope';
+/**
+ * Creates a {@link ReactiveScope | reactive scope} from which all form
+ * instances derive, and:
+ *
+ * - if a client loads a form within a Solid reactive context, the scope will be
+ *   disposed along with the client's reactive context; OR
+ * - if a client loads a form outside a Solid reactive context (typically: if a
+ *   client does not use Solid reactivity), the scope will disposed if and when
+ *   the engine drops access to the loaded form
+ *
+ * **IMPORTANT:** this **MUST** be called synchronously. If it is called in an
+ * `async` function, it **MUST** be called before any `await` expression; if it
+ * is called in any other flow with mixed synchrony, it must be called before
+ * yielding to the event loop. Failing to do this will cause the engine to lose
+ * access to a client's Solid reactive context, potentially leaking form
+ * reactivity indefinitely.
+ */
+export declare const createPotentiallyClientOwnedReactiveScope: () => ReactiveScope;