@getodk/xforms-engine 0.4.0 → 0.5.0

package/dist/client/StringNode.d.ts

@@ -1,46 +0,0 @@
-import { InputDefinition } from '../parse/body/control/InputDefinition.ts';
-import { LeafNodeDefinition } from '../parse/model/LeafNodeDefinition.ts';
-import { BaseNode, BaseNodeState } from './BaseNode.ts';
-import { NodeAppearances } from './NodeAppearances.ts';
-import { RootNode } from './RootNode.ts';
-import { GeneralParentNode } from './hierarchy.ts';
-import { LeafNodeValidationState } from './validation.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 LeafNodeDefinition {
-    readonly bodyElement: InputDefinition;
-}
-export type StringNodeAppearances = NodeAppearances<StringDefinition>;
-/**
- * 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 appearances: StringNodeAppearances;
-    readonly definition: StringDefinition;
-    readonly root: RootNode;
-    readonly parent: GeneralParentNode;
-    readonly currentState: StringNodeState;
-    readonly validationState: LeafNodeValidationState;
-    /**
-     * 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;
-}

package/dist/instance/StringField.d.ts

@@ -1,44 +0,0 @@
-import { Accessor } from 'solid-js';
-import { StringNode, StringNodeAppearances } from '../client/StringNode.ts';
-import { TextRange } from '../client/TextRange.ts';
-import { AnyViolation, LeafNodeValidationState } from '../client/validation.ts';
-import { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
-import { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
-import { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
-import { SimpleAtomicState } from '../lib/reactivity/types.ts';
-import { InputDefinition } from '../parse/body/control/InputDefinition.ts';
-import { LeafNodeDefinition } from '../parse/model/LeafNodeDefinition.ts';
-import { Root } from './Root.ts';
-import { DescendantNodeStateSpec, DescendantNode } from './abstract/DescendantNode.ts';
-import { GeneralParentNode } from './hierarchy.ts';
-import { EvaluationContext } from './internal-api/EvaluationContext.ts';
-import { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
-import { ValidationContext } from './internal-api/ValidationContext.ts';
-import { ValueContext } from './internal-api/ValueContext.ts';
-export interface StringFieldDefinition extends LeafNodeDefinition {
-    readonly bodyElement: InputDefinition;
-}
-interface StringFieldStateSpec extends DescendantNodeStateSpec<string> {
-    readonly label: Accessor<TextRange<'label'> | null>;
-    readonly hint: Accessor<TextRange<'hint'> | null>;
-    readonly children: null;
-    readonly value: SimpleAtomicState<string>;
-    readonly valueOptions: null;
-}
-export declare class StringField extends DescendantNode<StringFieldDefinition, StringFieldStateSpec, null> implements StringNode, EvaluationContext, SubscribableDependency, ValidationContext, ValueContext<string> {
-    private readonly validation;
-    protected readonly state: SharedNodeState<StringFieldStateSpec>;
-    protected engineState: EngineState<StringFieldStateSpec>;
-    readonly nodeType = "string";
-    readonly appearances: StringNodeAppearances;
-    readonly currentState: CurrentState<StringFieldStateSpec>;
-    get validationState(): LeafNodeValidationState;
-    readonly encodeValue: (value: string) => string;
-    readonly decodeValue: (value: string) => string;
-    constructor(parent: GeneralParentNode, definition: StringFieldDefinition);
-    getViolation(): AnyViolation | null;
-    isBlank(): boolean;
-    getChildren(): readonly [];
-    setValue(value: string): Root;
-}
-export {};

package/dist/instance/internal-api/SubscribableDependency.d.ts

@@ -1,59 +0,0 @@
-import { ReactiveScope } from '../../lib/reactivity/scope.ts';
-/**
- * Provides a common interface to explicitly establish a reactive subscription
- * to a form node, regardless of which node-specific details might trigger
- * reactive updates. This is primarily intended for use in coordination with a
- * node's {@link EvaluationContext} interface, so that computed expression
- * evaluations can be re-executed when their dependencies update, without
- * requiring a given evaluation to handle node-specific logic to determine
- * when/whether updates have occurred.
- *
- * @example Given a form with these bindings:
- *
- * ```xml
- * <bind nodeset="/data/field-1" />
- * <bind nodeset="/data/field-2" type="int" />
- * <bind nodeset="/data/group-a" relevant="/data/field-1 != ''" />
- * <bind nodeset="/data/group-a/field-a-1" calculate="/data/field-2 * 2" />
- * ```
- *
- * The field `/data/group-a/field-a-1`'s calculate has two dependencies:
- *
- * - `/data-field-2` (explicit)
- * - `/data/group-a` (implicit: non-relevance is inherited)
- *
- * (This is an oversimplification, but it helps to illustrate the concept.)
- *
- * The first dependency's subscription is clearly concerned with that leaf
- * node's value. In which case, that node's `subscribe` method should react to
- * updates to its value (e.g. its `currentState.value` or the internal reactive
- * representation thereof).
- *
- * Whereas the second dependency has no value (no parent nodes do); instead, the
- * subscription would be concerned with that node's relevance. In which case,
- * that node's `subscribe` method should react to updates to its relevance state
- * (e.g. its `currentState.relevant` or the internal reactive represeentation
- * thereof).
- *
- * @example Given a form with:
- *
- * ```xml
- * <!-- model -->
- * <bind nodeset="/data/repeat-a/field-a-1" calculate="position(..)" />
- * <!-- body -->
- * <repeat nodeset="/data/repeat-a" />
- * ```
- *
- * The field `/data/repeat-a/field-a-1` has a dependency on its containing
- * repeat instance. That node also doesn't have a value, and here the dynamic
- * aspect of the dependency is the node's current position. Here the node's
- * `subscribe` method should react to changes in its position (likely indirectly
- * by reading its `contextReference`).
- *
- * @see {@link EvaluationContext}
- * @see {@link EvaluationContext.contextReference}
- */
-export interface SubscribableDependency {
-    readonly scope: ReactiveScope;
-    readonly subscribe: VoidFunction;
-}

package/dist/parse/XFormDataType.d.ts

@@ -1,25 +0,0 @@
-import { CollectionValues } from '../../../common/types/collections/CollectionValues.ts';
-/**
- * Like JavaRosa. Presumably for explicit types which aren't impelemnted?
- */
-declare const UNSUPPORTED_DATA_TYPE = "UNSUPPORTED";
-export type UnsupportedDataType = typeof UNSUPPORTED_DATA_TYPE;
-/**
- * Like JavaRosa. Presumably for e.g. groups with explicit binds (`relevant` etc)?
- */
-export type NullDataType = 'NULL';
-/**
- * As in ODK XForms Spec.
- *
- * TODO: it's unclear why JavaRosa's `DataType` hews closely to the spec, but
- * has certain differences (e.g. string -> TEXT, int -> INTEGER). It's also
- * not immediately clear how additive types like CHOICE and MULTIPLE_ITEMS
- * square with the underlying spec types.
- */
-export declare const XFORM_SPEC_DATA_TYPES: readonly ["string", "int", "boolean", "decimal", "date", "time", "dateTime", "geopoint", "geotrace", "geoshape", "binary", "barcode", "intent"];
-export type XFormSpecDataType = CollectionValues<typeof XFORM_SPEC_DATA_TYPES>;
-export type XFormDataType = NullDataType | UnsupportedDataType | XFormSpecDataType;
-declare const DEFAULT_XFORM_DATA_TYPE = "string";
-export type DefaultXFormDataType = typeof DEFAULT_XFORM_DATA_TYPE;
-export declare const bindDataType: (bindType: string | null) => XFormDataType;
-export {};

package/src/client/StringNode.ts

@@ -1,52 +0,0 @@
-import type { InputDefinition } from '../parse/body/control/InputDefinition.ts';
-import type { LeafNodeDefinition } from '../parse/model/LeafNodeDefinition.ts';
-import type { BaseNode, BaseNodeState } from './BaseNode.ts';
-import type { NodeAppearances } from './NodeAppearances.ts';
-import type { RootNode } from './RootNode.ts';
-import type { GeneralParentNode } from './hierarchy.ts';
-import type { LeafNodeValidationState } from './validation.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 LeafNodeDefinition {
-	readonly bodyElement: InputDefinition;
-}
-
-export type StringNodeAppearances = NodeAppearances<StringDefinition>;
-
-/**
- * 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 appearances: StringNodeAppearances;
-	readonly definition: StringDefinition;
-	readonly root: RootNode;
-	readonly parent: GeneralParentNode;
-	readonly currentState: StringNodeState;
-	readonly validationState: LeafNodeValidationState;
-
-	/**
-	 * 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;
-}

package/src/instance/StringField.ts

@@ -1,120 +0,0 @@
-import { identity } from '@getodk/common/lib/identity.ts';
-import type { Accessor } from 'solid-js';
-import type { StringNode, StringNodeAppearances } from '../client/StringNode.ts';
-import type { TextRange } from '../client/TextRange.ts';
-import type { AnyViolation, LeafNodeValidationState } from '../client/validation.ts';
-import { createValueState } from '../lib/reactivity/createValueState.ts';
-import type { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
-import type { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
-import type { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
-import { createSharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
-import { createFieldHint } from '../lib/reactivity/text/createFieldHint.ts';
-import { createNodeLabel } from '../lib/reactivity/text/createNodeLabel.ts';
-import type { SimpleAtomicState } from '../lib/reactivity/types.ts';
-import type { SharedValidationState } from '../lib/reactivity/validation/createValidation.ts';
-import { createValidationState } from '../lib/reactivity/validation/createValidation.ts';
-import type { InputDefinition } from '../parse/body/control/InputDefinition.ts';
-import type { LeafNodeDefinition } from '../parse/model/LeafNodeDefinition.ts';
-import type { Root } from './Root.ts';
-import type { DescendantNodeStateSpec } from './abstract/DescendantNode.ts';
-import { DescendantNode } from './abstract/DescendantNode.ts';
-import type { GeneralParentNode } from './hierarchy.ts';
-import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
-import type { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
-import type { ValidationContext } from './internal-api/ValidationContext.ts';
-import type { ValueContext } from './internal-api/ValueContext.ts';
-
-export interface StringFieldDefinition extends LeafNodeDefinition {
-	readonly bodyElement: InputDefinition;
-}
-
-interface StringFieldStateSpec extends DescendantNodeStateSpec<string> {
-	readonly label: Accessor<TextRange<'label'> | null>;
-	readonly hint: Accessor<TextRange<'hint'> | null>;
-	readonly children: null;
-	readonly value: SimpleAtomicState<string>;
-	readonly valueOptions: null;
-}
-
-export class StringField
-	extends DescendantNode<StringFieldDefinition, StringFieldStateSpec, null>
-	implements
-		StringNode,
-		EvaluationContext,
-		SubscribableDependency,
-		ValidationContext,
-		ValueContext<string>
-{
-	private readonly validation: SharedValidationState;
-	protected readonly state: SharedNodeState<StringFieldStateSpec>;
-
-	// InstanceNode
-	protected engineState: EngineState<StringFieldStateSpec>;
-
-	// StringNode
-	readonly nodeType = 'string';
-	readonly appearances: StringNodeAppearances;
-	readonly currentState: CurrentState<StringFieldStateSpec>;
-
-	get validationState(): LeafNodeValidationState {
-		return this.validation.currentState;
-	}
-
-	// ValueContext
-	readonly encodeValue = identity<string>;
-
-	readonly decodeValue = identity<string>;
-
-	constructor(parent: GeneralParentNode, definition: StringFieldDefinition) {
-		super(parent, definition);
-
-		this.appearances = definition.bodyElement.appearances;
-
-		const sharedStateOptions = {
-			clientStateFactory: this.engineConfig.stateFactory,
-		};
-
-		const state = createSharedNodeState(
-			this.scope,
-			{
-				reference: this.contextReference,
-				readonly: this.isReadonly,
-				relevant: this.isRelevant,
-				required: this.isRequired,
-
-				label: createNodeLabel(this, definition),
-				hint: createFieldHint(this, definition),
-				children: null,
-				valueOptions: null,
-				value: createValueState(this),
-			},
-			sharedStateOptions
-		);
-
-		this.state = state;
-		this.engineState = state.engineState;
-		this.currentState = state.currentState;
-		this.validation = createValidationState(this, sharedStateOptions);
-	}
-
-	// ValidationContext
-	getViolation(): AnyViolation | null {
-		return this.validation.engineState.violation;
-	}
-
-	isBlank(): boolean {
-		return this.engineState.value === '';
-	}
-
-	// InstanceNode
-	getChildren(): readonly [] {
-		return [];
-	}
-
-	// StringNode
-	setValue(value: string): Root {
-		this.state.setProperty('value', value);
-
-		return this.root;
-	}
-}

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

@@ -1,61 +0,0 @@
-import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
-import type { EvaluationContext } from './EvaluationContext.ts';
-
-/**
- * Provides a common interface to explicitly establish a reactive subscription
- * to a form node, regardless of which node-specific details might trigger
- * reactive updates. This is primarily intended for use in coordination with a
- * node's {@link EvaluationContext} interface, so that computed expression
- * evaluations can be re-executed when their dependencies update, without
- * requiring a given evaluation to handle node-specific logic to determine
- * when/whether updates have occurred.
- *
- * @example Given a form with these bindings:
- *
- * ```xml
- * <bind nodeset="/data/field-1" />
- * <bind nodeset="/data/field-2" type="int" />
- * <bind nodeset="/data/group-a" relevant="/data/field-1 != ''" />
- * <bind nodeset="/data/group-a/field-a-1" calculate="/data/field-2 * 2" />
- * ```
- *
- * The field `/data/group-a/field-a-1`'s calculate has two dependencies:
- *
- * - `/data-field-2` (explicit)
- * - `/data/group-a` (implicit: non-relevance is inherited)
- *
- * (This is an oversimplification, but it helps to illustrate the concept.)
- *
- * The first dependency's subscription is clearly concerned with that leaf
- * node's value. In which case, that node's `subscribe` method should react to
- * updates to its value (e.g. its `currentState.value` or the internal reactive
- * representation thereof).
- *
- * Whereas the second dependency has no value (no parent nodes do); instead, the
- * subscription would be concerned with that node's relevance. In which case,
- * that node's `subscribe` method should react to updates to its relevance state
- * (e.g. its `currentState.relevant` or the internal reactive represeentation
- * thereof).
- *
- * @example Given a form with:
- *
- * ```xml
- * <!-- model -->
- * <bind nodeset="/data/repeat-a/field-a-1" calculate="position(..)" />
- * <!-- body -->
- * <repeat nodeset="/data/repeat-a" />
- * ```
- *
- * The field `/data/repeat-a/field-a-1` has a dependency on its containing
- * repeat instance. That node also doesn't have a value, and here the dynamic
- * aspect of the dependency is the node's current position. Here the node's
- * `subscribe` method should react to changes in its position (likely indirectly
- * by reading its `contextReference`).
- *
- * @see {@link EvaluationContext}
- * @see {@link EvaluationContext.contextReference}
- */
-export interface SubscribableDependency {
-	readonly scope: ReactiveScope;
-	readonly subscribe: VoidFunction;
-}

package/src/parse/XFormDataType.ts

@@ -1,62 +0,0 @@
-import type { CollectionValues } from '@getodk/common/types/collections/CollectionValues.ts';
-
-/**
- * Like JavaRosa. Presumably for explicit types which aren't impelemnted?
- */
-const UNSUPPORTED_DATA_TYPE = 'UNSUPPORTED';
-
-export type UnsupportedDataType = typeof UNSUPPORTED_DATA_TYPE;
-
-/**
- * Like JavaRosa. Presumably for e.g. groups with explicit binds (`relevant` etc)?
- */
-export type NullDataType = 'NULL';
-
-/**
- * As in ODK XForms Spec.
- *
- * TODO: it's unclear why JavaRosa's `DataType` hews closely to the spec, but
- * has certain differences (e.g. string -> TEXT, int -> INTEGER). It's also
- * not immediately clear how additive types like CHOICE and MULTIPLE_ITEMS
- * square with the underlying spec types.
- */
-export const XFORM_SPEC_DATA_TYPES = [
-	'string',
-	'int',
-	'boolean',
-	'decimal',
-	'date',
-	'time',
-	'dateTime',
-	'geopoint',
-	'geotrace',
-	'geoshape',
-	'binary',
-	'barcode',
-	'intent',
-] as const;
-
-const isSupportedDataType = (bindType: string): bindType is XFormSpecDataType =>
-	XFORM_SPEC_DATA_TYPES.includes(bindType as XFormSpecDataType);
-
-export type XFormSpecDataType = CollectionValues<typeof XFORM_SPEC_DATA_TYPES>;
-
-export type XFormDataType = NullDataType | UnsupportedDataType | XFormSpecDataType;
-
-const DEFAULT_XFORM_DATA_TYPE = 'string';
-
-export type DefaultXFormDataType = typeof DEFAULT_XFORM_DATA_TYPE;
-
-// TODO: groups -> NULL?
-// TODO: XSD namespace
-export const bindDataType = (bindType: string | null): XFormDataType => {
-	if (bindType == null) {
-		return DEFAULT_XFORM_DATA_TYPE;
-	}
-
-	if (isSupportedDataType(bindType)) {
-		return bindType;
-	}
-
-	return UNSUPPORTED_DATA_TYPE;
-};