@getodk/xforms-engine 0.1.0

package/dist/client/SubtreeNode.d.ts

@@ -0,0 +1,52 @@
+import type { SubtreeDefinition as BaseSubtreeDefinition } 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 SubtreeNodeState extends BaseNodeState {
+    get label(): null;
+    get hint(): null;
+    get children(): readonly GeneralChildNode[];
+    get valueOptions(): null;
+    get value(): null;
+}
+export interface SubtreeDefinition extends BaseSubtreeDefinition {
+    readonly bodyElement: null;
+}
+/**
+ * A non-root node which has children, but **no** corresponding XForms
+ * `<group>`. A subtree node does not have any direct implications for
+ * presentation to users, but its descendants may specify presentational details
+ * in their own {@link BaseNode.definition | definition}s.
+ *
+ * @example
+ *
+ * A common `SubtreeNode` case will be a form's `<meta>` element:
+ *
+ * ```xml
+ * <!-- /h:html/h:head/model -->
+ * <instance>
+ *   <data>
+ *     <some-group>
+ *       <some-field />
+ *     </some-group>
+ *     <!-- Note that `meta` does not have a corresponding group body element -->
+ *     <!-- SubtreeNode(/data/meta): { ... -->
+ *     <meta>
+ *       <instanceID/>
+ *     </meta>
+ *     <!-- } -->
+ *   </data>
+ * </instance>
+ * <!-- /h:html/h:body -->
+ * <group ref="/data/some-group">
+ *   <input ref="/data/some-group/some-field" />
+ * </group>
+ * ```
+ */
+export interface SubtreeNode extends BaseNode {
+    readonly nodeType: 'subtree';
+    readonly definition: SubtreeDefinition;
+    readonly root: RootNode;
+    readonly parent: GeneralParentNode;
+    readonly currentState: SubtreeNodeState;
+}

package/dist/client/TextRange.d.ts

@@ -0,0 +1,55 @@
+import type { ActiveLanguage } from './FormLanguage.ts';
+export type TextChunkSource = 'itext' | 'output' | 'static';
+/**
+ * @todo This (and everything else to do with {@link TextRange}s is for
+ * illustration purposes, as a starting point where any particular detail is of
+ * unknown utility. We can iterate on all aspects of text ranges in actual
+ * clients and refine from there.
+ *
+ * @see {@link TextRange}
+ */
+export interface TextChunk {
+    readonly source: TextChunkSource;
+    /**
+     * @see {@link ActiveLanguage} for additional commentary
+     */
+    get language(): ActiveLanguage;
+    get asString(): string;
+    get formatted(): unknown;
+}
+/**
+ * Represents aspects of a form which produce text, which _might_ be:
+ *
+ * - Computed from multiple sources
+ * - Capable of conveying certain formatting (which may be presentational and/or
+ *   structural)
+ *
+ * Computed text values may be updated by:
+ *
+ * - Changing a {@link RootNodeState.activeLanguage | form's active language}
+ * - Changes to any state referenced by an
+ *   {@link https://getodk.github.io/xforms-spec/#body-elements | output},
+ *   within any text-presenting aspect of a form (e.g. labels and hints, as well
+ *   as itext translations referenced by those)
+ *
+ * As a client interface, the intent is to convey that this text may be dynamic
+ * (and thus potentially reactive for clients supplying a
+ * {@link OpaqueReactiveObjectFactory}), and may produce multiple spans of text
+ * (or none at all) depending on the structure and state of the form.
+ *
+ * @todo This interface should be considered **incomplete and in flux**, and
+ * subject to change as we evaluate client needs and engine responsibilities. In
+ * particular, we've deferred a notion of an interface for formatting aspects,
+ * while leaving open the possibility that it may come in future iterations.
+ *
+ * {@link role} is intended to convey that individual text ranges may be
+ * reasoned about differently by clients depending on their role (for instance,
+ * a text range's role may correspond to the "short" or "guidance" `form` of a
+ * {@link https://getodk.github.io/xforms-spec/#languages | translation}).
+ */
+export interface TextRange<Role extends string | null = null> {
+    readonly role: Role;
+    [Symbol.iterator](): Iterable<TextChunk>;
+    get asString(): string;
+    get formatted(): unknown;
+}

package/dist/client/hierarchy.d.ts

@@ -0,0 +1,48 @@
+import type { ExpandUnion } from '../../../common/types/helpers.d.ts';
+import type { GroupNode } from './GroupNode.ts';
+import type { RepeatInstanceNode } from './RepeatInstanceNode.ts';
+import type { RepeatRangeNode } from './RepeatRangeNode.ts';
+import type { RootNode } from './RootNode.ts';
+import type { SelectNode } from './SelectNode.ts';
+import type { StringNode } from './StringNode.ts';
+import type { SubtreeNode } from './SubtreeNode.ts';
+export type AnyLeafNode = SelectNode | StringNode;
+/**
+ * Any of the concrete node types which may be a parent of any other node.
+ *
+ * This is an intermediate type, which shouldn't be referenced by other concrete
+ * node types directly. Instead:
+ *
+ * - Repeat instances should (continue to) specify {@link RepeatRangeNode}.
+ * - All other child nodes should specify {@link GeneralParentNode}.
+ */
+export type AnyParentNode = RootNode | SubtreeNode | GroupNode | RepeatRangeNode | RepeatInstanceNode;
+/**
+ * Any of the concrete node types a client may get from the engine's form
+ * representation. This union should be updated when any new concrete node type
+ * is added (or when any of the current members is changed/removed).
+ *
+ * @see {@link GeneralParentNode}, which is derived from this type
+ * @see {@link GeneralChildNode}, which is derived from this type
+ */
+export type AnyNode = ExpandUnion<AnyLeafNode | AnyParentNode>;
+/**
+ * Any of the concrete node types which may be a parent of non-repeat instance
+ * child nodes.
+ */
+export type GeneralParentNode = Exclude<AnyParentNode, RepeatRangeNode>;
+/**
+ * Any of the concrete node types which may be a child of any other node.
+ *
+ * This is an intermediate type, which shouldn't be referenced by other concrete
+ * node types directly. Instead:
+ *
+ * - Repeat ranges should (continue to) specify {@link RepeatInstanceNode}.
+ * - All other parent nodes should specify {@link GeneralChildNode}.
+ */
+export type AnyChildNode = Exclude<AnyNode, RootNode>;
+/**
+ * Any of the concrete node types which may be a child of non-repeat range
+ * parent nodes.
+ */
+export type GeneralChildNode = Exclude<AnyChildNode, RepeatInstanceNode>;

package/dist/client/index.d.ts

@@ -0,0 +1,11 @@
+import type { EngineConfig } from './EngineConfig.ts';
+import type { RootNode } from './RootNode.ts';
+export type FormResource = Blob | URL | string;
+export interface InitializeFormOptions {
+    readonly config: EngineConfig;
+    readonly initialState?: FormResource;
+}
+/**
+ * Creates an instance of a form to be filled (or edited) by a client.
+ */
+export type InitializeForm = (input: FormResource, options?: InitializeFormOptions) => Promise<RootNode>;

package/dist/client/node-types.d.ts

@@ -0,0 +1 @@
+export type InstanceNodeType = 'root' | 'repeat-range' | 'repeat-instance' | 'group' | 'subtree' | 'select' | 'string';

package/dist/expression/DependencyContext.d.ts

@@ -0,0 +1,12 @@
+import type { AnyDependentExpression } from './DependentExpression.ts';
+export declare abstract class DependencyContext {
+    abstract get parentReference(): string | null;
+    abstract get reference(): string | null;
+    protected readonly dependentExpressions: Set<AnyDependentExpression>;
+    protected dependencyExpressionsCache: ReadonlySet<string> | null;
+    get dependencyExpressions(): ReadonlySet<string>;
+    get isTranslated(): boolean;
+    set isTranslated(value: true);
+    protected _isTranslated: boolean;
+    registerDependentExpression(expression: AnyDependentExpression): void;
+}

package/dist/expression/DependentExpression.d.ts

@@ -0,0 +1,43 @@
+import type { XFormsXPathEvaluator } from '@getodk/xpath';
+import type { DependencyContext } from './DependencyContext.ts';
+declare const evaluatorMethodsByResultType: {
+    readonly boolean: "evaluateBoolean";
+    readonly nodes: "evaluateNodes";
+    readonly string: "evaluateString";
+};
+type EvaluatorMethodsByResultType = typeof evaluatorMethodsByResultType;
+export type DependentExpressionResultType = keyof EvaluatorMethodsByResultType;
+export type DependentExpressionEvaluatorMethod<Type extends DependentExpressionResultType> = EvaluatorMethodsByResultType[Type];
+export type DependentExpressionResult<Type extends DependentExpressionResultType> = ReturnType<XFormsXPathEvaluator[DependentExpressionEvaluatorMethod<Type>]>;
+interface SemanticDependencyOptions {
+    /**
+     * @default false
+     */
+    readonly parentContext?: boolean | undefined;
+    /**
+     * @default false
+     */
+    readonly translations?: boolean | undefined;
+}
+interface DependentExpressionOptions {
+    /**
+     * @default false
+     */
+    readonly ignoreContextReference?: boolean;
+    /**
+     * @default true
+     */
+    readonly ignoreNullExpressions?: boolean;
+    readonly semanticDependencies?: SemanticDependencyOptions;
+}
+export declare class DependentExpression<Type extends DependentExpressionResultType> {
+    readonly resultType: Type;
+    readonly expression: string;
+    readonly dependencyReferences: ReadonlySet<string>;
+    readonly isTranslated: boolean;
+    readonly evaluatorMethod: DependentExpressionEvaluatorMethod<Type>;
+    constructor(context: DependencyContext, resultType: Type, expression: string, options?: DependentExpressionOptions);
+    toString(): string | null;
+}
+export type AnyDependentExpression = DependentExpression<any>;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import type { InitializeForm } from './index.ts';
+export declare const initializeForm: InitializeForm;
+export type * from './client/EngineConfig.ts';
+export type * from './client/FormLanguage.ts';
+export type * from './client/GroupNode.ts';
+export type * from './client/OpaqueReactiveObjectFactory.ts';
+export type * from './client/RepeatInstanceNode.ts';
+export type * from './client/RepeatRangeNode.ts';
+export type * from './client/RootNode.ts';
+export type * from './client/SelectNode.ts';
+export type * from './client/StringNode.ts';
+export type * from './client/SubtreeNode.ts';
+export type * from './client/TextRange.ts';
+export type { AnyChildNode, AnyLeafNode, AnyNode, AnyParentNode, GeneralChildNode, GeneralParentNode, } from './client/hierarchy.ts';
+export type * from './client/index.ts';
+export type { AnySelectDefinition, SelectDefinition, } from './body/control/select/SelectDefinition.ts';