@getodk/xforms-engine 0.1.1 → 0.3.0

package/dist/body/text/TextElementOutputPart.d.ts

@@ -1,13 +0,0 @@
-import { AnyTextElementDefinition } from './TextElementDefinition.ts';
-import { TextElementPart } from './TextElementPart.ts';
-
-interface OutputElement extends Element {
-    readonly localName: 'output';
-    getAttribute(name: 'value'): string;
-    getAttribute(name: string): string | null;
-}
-export declare class TextElementOutputPart extends TextElementPart<'output'> {
-    static from(context: AnyTextElementDefinition, element: Element): TextElementOutputPart | null;
-    protected constructor(context: AnyTextElementDefinition, element: OutputElement);
-}
-export {};

package/dist/body/text/TextElementPart.d.ts

@@ -1,13 +0,0 @@
-import { DependentExpression } from '../../expression/DependentExpression.ts';
-import { AnyTextElementDefinition } from './TextElementDefinition.ts';
-import { TextElementOutputPart } from './TextElementOutputPart.ts';
-import { TextElementReferencePart } from './TextElementReferencePart.ts';
-import { TextElementStaticPart } from './TextElementStaticPart.ts';
-
-export type TextElementPartType = 'output' | 'reference' | 'static';
-export declare abstract class TextElementPart<Type extends TextElementPartType> extends DependentExpression<'string'> {
-    readonly type: Type;
-    readonly stringValue?: string;
-    constructor(type: Type, context: AnyTextElementDefinition, expression: string);
-}
-export type AnyTextElementPart = TextElementOutputPart | TextElementReferencePart | TextElementStaticPart;

package/dist/body/text/TextElementReferencePart.d.ts

@@ -1,7 +0,0 @@
-import { AnyTextElementDefinition, TextElement } from './TextElementDefinition.ts';
-import { TextElementPart } from './TextElementPart.ts';
-
-export declare class TextElementReferencePart extends TextElementPart<'reference'> {
-    static from(context: AnyTextElementDefinition, element: TextElement): TextElementReferencePart | null;
-    protected constructor(context: AnyTextElementDefinition, expression: string);
-}

package/dist/body/text/TextElementStaticPart.d.ts

@@ -1,7 +0,0 @@
-import { AnyTextElementDefinition } from './TextElementDefinition.ts';
-import { TextElementPart } from './TextElementPart.ts';
-
-export declare class TextElementStaticPart extends TextElementPart<'static'> {
-    readonly stringValue: string;
-    constructor(context: AnyTextElementDefinition, node: Text);
-}

package/dist/instance/RepeatRange.d.ts

@@ -1,80 +0,0 @@
-import { Accessor } from 'solid-js';
-import { RepeatRangeNode } from '../client/RepeatRangeNode.ts';
-import { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.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 { RepeatSequenceDefinition } from '../model/RepeatSequenceDefinition.ts';
-import { RepeatDefinition, RepeatInstance } from './RepeatInstance.ts';
-import { Root } from './Root.ts';
-import { DescendantNodeSharedStateSpec, DescendantNode } from './abstract/DescendantNode.ts';
-import { GeneralParentNode } from './hierarchy.ts';
-import { NodeID } from './identity.ts';
-import { EvaluationContext } from './internal-api/EvaluationContext.ts';
-import { SubscribableDependency } from './internal-api/SubscribableDependency.ts';
-import { TextRange } from './text/TextRange.ts';
-
-interface RepeatRangeStateSpec extends DescendantNodeSharedStateSpec {
-    readonly hint: null;
-    readonly label: Accessor<TextRange<'label'> | null>;
-    readonly children: Accessor<readonly NodeID[]>;
-    readonly valueOptions: null;
-    readonly value: null;
-}
-export declare class RepeatRange extends DescendantNode<RepeatSequenceDefinition, RepeatRangeStateSpec, RepeatInstance> implements RepeatRangeNode, EvaluationContext, SubscribableDependency {
-    /**
-     * A repeat range doesn't have a corresponding primary instance element of its
-     * own, and its instances are appended to the range's parent element. During
-     * creation of the initial primary instance state and DOM trees, we _could_
-     * reliably append all of the range's instances in order as the definition
-     * tree is recursed. But that would fail to handle some instance addition
-     * cases afterwards.
-     *
-     * Most notably, we need to know where in the primary instance tree to append
-     * instances created for a range which is currently empty. As a lucky
-     * coincidence, this need coincides with the ability to add instances at any
-     * arbitrary index within the range. In each case, we can reference a primary
-     * instance DOM node which will become the new instance's preceding sibling.
-     * Where the range is empty, we use this {@link Comment} node (itself created
-     * and appended during range initialization) in lieu of a nonexistent
-     * preceding instance's {@link contextNode}.
-     *
-     * @todo We likely want to remove these during submission serialization.
-     * @todo Can we use a
-     * {@link https://developer.mozilla.org/en-US/docs/Web/API/Range | DOM Range}
-     * instead?
-     */
-    private readonly anchorNode;
-    private readonly childrenState;
-    protected readonly state: SharedNodeState<RepeatRangeStateSpec>;
-    protected engineState: EngineState<RepeatRangeStateSpec>;
-    readonly nodeType = "repeat-range";
-    readonly currentState: MaterializedChildren<CurrentState<RepeatRangeStateSpec>, RepeatInstance>;
-    constructor(parent: GeneralParentNode, definition: RepeatSequenceDefinition);
-    private getLastIndex;
-    protected initializeContextNode(parentContextNode: Element): Element;
-    protected computeReference(parent: GeneralParentNode): string;
-    getInstanceIndex(instance: RepeatInstance): number;
-    addInstances(afterIndex?: number, count?: number, definition?: RepeatDefinition): Root;
-    /**
-     * Removes the {@link RepeatInstance}s corresponding to the specified range of
-     * indexes, and then removes those repeat instances from the repeat range's
-     * own children state in that order:
-     *
-     * 1. Identify the set of {@link RepeatInstance}s to be removed.
-     *
-     * 2. For each {@link RepeatInstance} pending removal, perform that node's
-     *    removal logic. @see {@link RepeatInstance.remove} for more detail.
-     *
-     * 3. Finalize update to the repeat range's own {@link childrenState},
-     *    omitting those {@link RepeatInstance}s which were removed.
-     *
-     * This ordering ensures a consistent representation of state is established
-     * prior to any downstream reactive updates, and ensures that removed nodes'
-     * reactivity is cleaned up.
-     */
-    removeInstances(startIndex: number, count?: number): Root;
-    subscribe(): void;
-    getChildren(): readonly RepeatInstance[];
-}
-export {};

package/dist/lib/xpath/analysis.d.ts

@@ -1,23 +0,0 @@
-import { AnySyntaxNode } from '@getodk/xpath/static/grammar/SyntaxNode.js';
-
-export type SingleChildNode = Extract<AnySyntaxNode, {
-    readonly children: readonly [AnySyntaxNode];
-}>;
-export declare const isItextFunctionCalled: (expression: string) => boolean;
-interface GetNodesetDependenciesOptions {
-    readonly contextReference?: string | null;
-    /**
-     * @default false
-     */
-    readonly ignoreContextReference?: boolean;
-    /**
-     * Ignores location path sub-expressions whose full text is `null`. While this
-     * is technically a valid relative name test step, it seems that real forms in
-     * the wild use it as if XPath had an actual `null` token/value.
-     *
-     * @default true
-     */
-    readonly ignoreNullExpressions?: boolean;
-}
-export declare const getNodesetDependencies: (expression: string, options?: GetNodesetDependenciesOptions) => Set<string>;
-export {};

package/dist/model/RepeatSequenceDefinition.d.ts

@@ -1,20 +0,0 @@
-import { RepeatGroupDefinition } from '../body/group/RepeatGroupDefinition.ts';
-import { BindDefinition } from './BindDefinition.ts';
-import { DescendentNodeDefinition } from './DescendentNodeDefinition.ts';
-import { NodeDefinition, ParentNodeDefinition } from './NodeDefinition.ts';
-import { RepeatInstanceDefinition } from './RepeatInstanceDefinition.ts';
-import { RepeatTemplateDefinition } from './RepeatTemplateDefinition.ts';
-
-export declare class RepeatSequenceDefinition extends DescendentNodeDefinition<'repeat-sequence', RepeatGroupDefinition> implements NodeDefinition<'repeat-sequence'> {
-    static createTemplateElement(instanceElement: Element): Element;
-    static createInstanceElement(templateElement: Element): Element;
-    readonly type = "repeat-sequence";
-    readonly template: RepeatTemplateDefinition;
-    readonly children: null;
-    readonly instances: RepeatInstanceDefinition[];
-    readonly node: null;
-    readonly nodeName: string;
-    readonly defaultValue: null;
-    constructor(parent: ParentNodeDefinition, bind: BindDefinition, bodyElement: RepeatGroupDefinition, modelNodes: readonly [Element, ...Element[]]);
-    toJSON(): Omit<this, "toJSON" | "parent" | "bind" | "root" | "bodyElement">;
-}

package/src/body/RepeatDefinition.ts

@@ -1,54 +0,0 @@
-import { JAVAROSA_NAMESPACE_URI } from '@getodk/common/constants/xmlns.ts';
-import type { XFormDefinition } from '../XFormDefinition.ts';
-import type { BodyElementDefinitionArray } from './BodyDefinition.ts';
-import { BodyElementDefinition } from './BodyElementDefinition.ts';
-import type { RepeatGroupDefinition } from './group/RepeatGroupDefinition.ts';
-
-export class RepeatDefinition extends BodyElementDefinition<'repeat'> {
-	override readonly category = 'structure';
-	readonly type = 'repeat';
-	override readonly reference: string;
-
-	// TODO: this will fall into the growing category of non-`BindExpression`
-	// cases which have roughly the same design story.
-	readonly countExpression: string | null;
-
-	readonly isFixedCount: boolean;
-
-	readonly children: BodyElementDefinitionArray;
-
-	constructor(
-		form: XFormDefinition,
-		readonly groupDefinition: RepeatGroupDefinition,
-		element: Element
-	) {
-		super(form, groupDefinition, element);
-
-		const reference = element.getAttribute('nodeset');
-
-		if (reference == null) {
-			throw new Error('Invalid repeat: missing `nodeset` reference');
-		}
-
-		this.reference = reference;
-		this.countExpression = element.getAttributeNS(JAVAROSA_NAMESPACE_URI, 'count');
-		this.children = groupDefinition.getChildren(element);
-
-		// Spec says this can be either `true()` or `false()`. That said, it
-		// could also presumably be `true ( )` or whatever.
-		const noAddRemove =
-			element
-				.getAttributeNS(JAVAROSA_NAMESPACE_URI, 'noAddRemove')
-				?.trim()
-				.replaceAll(/\s+/g, '') ?? 'false()';
-
-		// TODO: **probably** safe to disregard anything else?
-		this.isFixedCount = noAddRemove === 'true()';
-	}
-
-	override toJSON() {
-		const { form, groupDefinition, parent, ...rest } = this;
-
-		return rest;
-	}
-}

package/src/body/group/RepeatGroupDefinition.ts

@@ -1,91 +0,0 @@
-import { getRepeatElement } from '../../lib/dom/query.ts';
-import type { XFormDefinition } from '../../XFormDefinition.ts';
-import type { BodyElementDefinitionArray, BodyElementParentContext } from '../BodyDefinition.ts';
-import { RepeatDefinition } from '../RepeatDefinition.ts';
-import { BaseGroupDefinition } from './BaseGroupDefinition.ts';
-
-/**
- * TODO: The `RepeatGroupDefinition`/`RepeatDefinition` types are currently
- * expected to always pair, mirroring the corresponding XForm structure, e.g.
- *
- * ```xml
- * <group ref="/root/rep"> <!-- RepeatGroupDefinition -->
- *   <repeat nodeset="/root/rep" /> <!-- RepeatDefinition -->
- * </group>
- * ```
- *
- * This structure has already been a source of one bug (where a recursive walk
- * through a `BodyDefinition`'s descendants failed to reach the children of
- * `RepeatDefinition`s). It seems likely this will continue to be a footgun.
- * After some discussion with @lognaturel, I concluded that the pairing isn't
- * strictly necessary, as this should be considered invalid:
- *
- * ```xml
- * <group ref="/root/rep">
- *   <repeat nodeset="/root/rep" />
- *   <input ref="/root/rep/not-a-repeat-child" />
- * </group>
- * ```
- *
- * It **may** make sense to collapse these types in the future, but I've held
- * off, following another discussion with @lognaturel. There's some potential
- * for group/repeat labeling ambiguity.
- *
- * - The current design accommodates sharing a repeat-containing group's label
- *   across multiple repeat instances, but
- * - The
- *   {@link https://github.com/getodk/xforms-spec/blob/791753a09fabd3d64d8cb95776dc0cef71fa4446/_sections/60-repeats.md?plain=1#L46 | ODK XForms spec suggests}
- *   a repeat's first group might be a better candidate
- *
- * Example of such a structure:
- *
- * ```xml
- * <group ref="/root/foo">
- *   <label>Foo (outer label)</label>
- *   <repeat nodeset="/root/foo">
- *     <group>
- *       <label>Foo (inner label)</label>
- *       <!-- ... -->
- *     </group>
- *   </repeat>
- * </group>
- * ```
- */
-// eslint-disable-next-line @typescript-eslint/ban-ts-comment
-// @ts-ignore - All this so I could attach a JSDoc comment to something other
-// than the actual class...
-// eslint-disable-next-line @typescript-eslint/no-empty-interface, @typescript-eslint/no-unused-vars
-interface IgnoreMeIAmJustHereForTheJSDoc {}
-
-export class RepeatGroupDefinition extends BaseGroupDefinition<'repeat-group'> {
-	static override isCompatible(localName: string, element: Element): boolean {
-		return this.getGroupType(localName, element) === 'repeat-group';
-	}
-
-	readonly type = 'repeat-group';
-
-	readonly repeat: RepeatDefinition;
-
-	get repeatChildren(): BodyElementDefinitionArray {
-		return this.repeat.children;
-	}
-
-	constructor(form: XFormDefinition, parent: BodyElementParentContext, element: Element) {
-		// TODO: this has already been queried at least twice before reaching this
-		// point!
-		const repeat = getRepeatElement(element);
-
-		// TODO: and as such, this should not happen
-		if (repeat == null) {
-			throw new Error('Invalid repeat-group');
-		}
-
-		super(form, parent, element);
-
-		const repeatDefinition = new RepeatDefinition(form, this, repeat);
-
-		this.repeat = repeatDefinition;
-	}
-}
-
-export type RepeatGroupDefinitionClass = typeof RepeatGroupDefinition;

package/src/body/text/HintDefinition.ts

@@ -1,26 +0,0 @@
-import { getHintElement } from '../../lib/dom/query.ts';
-import type { XFormDefinition } from '../../XFormDefinition.ts';
-import type { AnyControlDefinition } from '../control/ControlDefinition.ts';
-import type { TextElement } from './TextElementDefinition.ts';
-import { TextElementDefinition } from './TextElementDefinition.ts';
-
-export interface HintElement extends TextElement {
-	readonly localName: 'hint';
-}
-
-export class HintDefinition extends TextElementDefinition<'hint'> {
-	static forElement(
-		form: XFormDefinition,
-		definition: AnyControlDefinition
-	): HintDefinition | null {
-		const hintElement = getHintElement(definition.element);
-
-		if (hintElement == null) {
-			return null;
-		}
-
-		return new this(form, definition, hintElement);
-	}
-
-	readonly type = 'hint';
-}

package/src/body/text/LabelDefinition.ts

@@ -1,54 +0,0 @@
-import { getLabelElement } from '../../lib/dom/query.ts';
-import type { XFormDefinition } from '../../XFormDefinition.ts';
-import type { AnyControlDefinition } from '../control/ControlDefinition.ts';
-import type { ItemDefinition } from '../control/select/ItemDefinition.ts';
-import type { ItemsetDefinition } from '../control/select/ItemsetDefinition.ts';
-import type { BaseGroupDefinition } from '../group/BaseGroupDefinition.ts';
-import type { TextElement, TextElementOwner } from './TextElementDefinition.ts';
-import { TextElementDefinition } from './TextElementDefinition.ts';
-
-export interface LabelElement extends TextElement {
-	readonly localName: 'label';
-}
-
-type StaticLabelContext = Exclude<TextElementOwner, ItemsetDefinition>;
-
-export class LabelDefinition extends TextElementDefinition<'label'> {
-	protected static staticDefinition(
-		form: XFormDefinition,
-		definition: StaticLabelContext
-	): LabelDefinition | null {
-		const labelElement = getLabelElement(definition.element);
-
-		if (labelElement == null) {
-			return null;
-		}
-
-		return new this(form, definition, labelElement);
-	}
-
-	static forControl(form: XFormDefinition, control: AnyControlDefinition): LabelDefinition | null {
-		return this.staticDefinition(form, control);
-	}
-
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	static forGroup(form: XFormDefinition, group: BaseGroupDefinition<any>): LabelDefinition | null {
-		return this.staticDefinition(form, group);
-	}
-
-	static forItem(form: XFormDefinition, item: ItemDefinition): LabelDefinition | null {
-		return this.staticDefinition(form, item);
-	}
-
-	static forItemset(form: XFormDefinition, itemset: ItemsetDefinition): LabelDefinition | null {
-		const labelElement = getLabelElement(itemset.element);
-
-		if (labelElement == null) {
-			return null;
-		}
-
-		return new this(form, itemset, labelElement);
-	}
-
-	readonly type = 'label';
-}

package/src/body/text/TextElementDefinition.ts

@@ -1,97 +0,0 @@
-import { isCommentNode, isElementNode, isTextNode } from '@getodk/common/lib/dom/predicates.ts';
-import type { XFormDefinition } from '../../XFormDefinition.ts';
-import { type AnyDependentExpression } from '../../expression/DependentExpression.ts';
-import type { AnyGroupElementDefinition } from '../BodyDefinition.ts';
-import { BodyElementDefinition } from '../BodyElementDefinition.ts';
-import type { InputDefinition } from '../control/InputDefinition.ts';
-import type { ItemDefinition } from '../control/select/ItemDefinition.ts';
-import type { ItemsetDefinition } from '../control/select/ItemsetDefinition.ts';
-import type { AnySelectDefinition } from '../control/select/SelectDefinition.ts';
-import { TextElementOutputPart } from './TextElementOutputPart.ts';
-import { TextElementReferencePart } from './TextElementReferencePart.ts';
-import { TextElementStaticPart } from './TextElementStaticPart.ts';
-
-export type TextElementType = 'hint' | 'label';
-
-export interface TextElement extends Element {
-	readonly localName: TextElementType;
-}
-
-export type TextElementOwner =
-	| AnyGroupElementDefinition
-	| AnySelectDefinition
-	| InputDefinition
-	| ItemDefinition
-	| ItemsetDefinition;
-
-export type TextElementChild = TextElementOutputPart | TextElementStaticPart;
-
-export abstract class TextElementDefinition<
-	Type extends TextElementType,
-> extends BodyElementDefinition<Type> {
-	readonly category = 'support';
-	abstract override readonly type: Type;
-
-	override readonly reference: string | null;
-	override readonly parentReference: string | null;
-
-	readonly referenceExpression: TextElementReferencePart | null;
-	readonly children: readonly TextElementChild[];
-
-	override get isTranslated(): boolean {
-		return this.owner.isTranslated;
-	}
-
-	override set isTranslated(value: true) {
-		this.owner.isTranslated = value;
-	}
-
-	protected constructor(
-		form: XFormDefinition,
-		readonly owner: TextElementOwner,
-		element: TextElement
-	) {
-		super(form, owner, element);
-
-		this.reference = owner.reference;
-		this.parentReference = owner.parentReference;
-		this.referenceExpression = TextElementReferencePart.from(this, element);
-
-		const children = Array.from(element.childNodes).flatMap((node) => {
-			if (isTextNode(node)) {
-				return new TextElementStaticPart(this, node);
-			}
-
-			if (isElementNode(node)) {
-				const output = TextElementOutputPart.from(this, node);
-
-				if (output != null) {
-					return output;
-				}
-			}
-
-			if (isCommentNode(node)) {
-				return [];
-			}
-
-			// eslint-disable-next-line no-console
-			console.error('Unexpected text element child', node);
-
-			throw new Error(`Unexpected <${element.nodeName}> child element`);
-		});
-
-		this.children = children;
-	}
-
-	override registerDependentExpression(expression: AnyDependentExpression): void {
-		this.owner.registerDependentExpression(expression);
-	}
-
-	override toJSON(): object {
-		const { form, owner, parent, ...rest } = this;
-
-		return rest;
-	}
-}
-
-export type AnyTextElementDefinition = TextElementDefinition<TextElementType>;

package/src/body/text/TextElementOutputPart.ts

@@ -1,27 +0,0 @@
-import type { AnyTextElementDefinition } from './TextElementDefinition.ts';
-import { TextElementPart } from './TextElementPart.ts';
-
-interface OutputElement extends Element {
-	readonly localName: 'output';
-
-	getAttribute(name: 'value'): string;
-	getAttribute(name: string): string | null;
-}
-
-const isOutputElement = (element: Element): element is OutputElement => {
-	return element.localName === 'output' && element.hasAttribute('value');
-};
-
-export class TextElementOutputPart extends TextElementPart<'output'> {
-	static from(context: AnyTextElementDefinition, element: Element): TextElementOutputPart | null {
-		if (isOutputElement(element)) {
-			return new this(context, element);
-		}
-
-		return null;
-	}
-
-	protected constructor(context: AnyTextElementDefinition, element: OutputElement) {
-		super('output', context, element.getAttribute('value'));
-	}
-}

package/src/body/text/TextElementPart.ts

@@ -1,31 +0,0 @@
-import { DependentExpression } from '../../expression/DependentExpression.ts';
-import type { AnyTextElementDefinition } from './TextElementDefinition.ts';
-import type { TextElementOutputPart } from './TextElementOutputPart.ts';
-import type { TextElementReferencePart } from './TextElementReferencePart.ts';
-import type { TextElementStaticPart } from './TextElementStaticPart.ts';
-
-export type TextElementPartType = 'output' | 'reference' | 'static';
-
-export abstract class TextElementPart<
-	Type extends TextElementPartType,
-> extends DependentExpression<'string'> {
-	readonly stringValue?: string;
-
-	constructor(
-		readonly type: Type,
-		context: AnyTextElementDefinition,
-		expression: string
-	) {
-		super(context, 'string', expression, {
-			semanticDependencies: {
-				translations: type !== 'static',
-			},
-			ignoreContextReference: true,
-		});
-	}
-}
-
-export type AnyTextElementPart =
-	| TextElementOutputPart
-	| TextElementReferencePart
-	| TextElementStaticPart;

package/src/body/text/TextElementReferencePart.ts

@@ -1,21 +0,0 @@
-import type { AnyTextElementDefinition, TextElement } from './TextElementDefinition.ts';
-import { TextElementPart } from './TextElementPart.ts';
-
-export class TextElementReferencePart extends TextElementPart<'reference'> {
-	static from(
-		context: AnyTextElementDefinition,
-		element: TextElement
-	): TextElementReferencePart | null {
-		const expression = element.getAttribute('ref');
-
-		if (expression == null) {
-			return null;
-		}
-
-		return new this(context, expression);
-	}
-
-	protected constructor(context: AnyTextElementDefinition, expression: string) {
-		super('reference', context, expression);
-	}
-}

package/src/body/text/TextElementStaticPart.ts

@@ -1,26 +0,0 @@
-import type { AnyTextElementDefinition } from './TextElementDefinition.ts';
-import { TextElementPart } from './TextElementPart.ts';
-
-const toStaticXPathExpression = (staticTextValue: string): string => {
-	const quote = staticTextValue.includes('"') ? "'" : '"';
-
-	if (staticTextValue.includes(quote)) {
-		// throw new Error('todo concat()');
-		return 'todo(concat())';
-	}
-
-	return `${quote}${staticTextValue}${quote}`;
-};
-
-export class TextElementStaticPart extends TextElementPart<'static'> {
-	override readonly stringValue: string;
-
-	constructor(context: AnyTextElementDefinition, node: Text) {
-		const stringValue = node.data;
-		const expression = toStaticXPathExpression(stringValue);
-
-		super('static', context, expression);
-
-		this.stringValue = stringValue;
-	}
-}