@getodk/xforms-engine 0.1.1 → 0.2.0

package/dist/instance/Group.d.ts

@@ -1,5 +1,5 @@
 import { Accessor } from 'solid-js';
-import { GroupDefinition, GroupNode } from '../client/GroupNode.ts';
+import { GroupDefinition, GroupNode, GroupNodeAppearances } from '../client/GroupNode.ts';
 import { TextRange } from '../index.ts';
 import { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
 import { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
@@ -22,10 +22,10 @@ export declare class Group extends DescendantNode<GroupDefinition, GroupStateSpe
     private readonly childrenState;
     protected readonly state: SharedNodeState<GroupStateSpec>;
     protected engineState: EngineState<GroupStateSpec>;
-    readonly currentState: MaterializedChildren<CurrentState<GroupStateSpec>, GeneralChildNode>;
     readonly nodeType = "group";
+    readonly appearances: GroupNodeAppearances;
+    readonly currentState: MaterializedChildren<CurrentState<GroupStateSpec>, GeneralChildNode>;
     constructor(parent: GeneralParentNode, definition: GroupDefinition);
-    protected computeReference(parent: GeneralParentNode): string;
     getChildren(): readonly GeneralChildNode[];
 }
 export {};

package/dist/instance/RepeatInstance.d.ts

@@ -1,5 +1,5 @@
 import { Accessor } from 'solid-js';
-import { RepeatDefinition, RepeatInstanceNode } from '../client/RepeatInstanceNode.ts';
+import { RepeatDefinition, RepeatInstanceNode, RepeatInstanceNodeAppearances } from '../client/RepeatInstanceNode.ts';
 import { TextRange } from '../index.ts';
 import { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
 import { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
@@ -30,10 +30,34 @@ export declare class RepeatInstance extends DescendantNode<RepeatDefinition, Rep
     private readonly currentIndex;
     protected readonly state: SharedNodeState<RepeatInstanceStateSpec>;
     protected engineState: EngineState<RepeatInstanceStateSpec>;
+    /**
+     * @todo Should we special case repeat `readonly` inheritance the same way
+     * we do for `relevant`?
+     *
+     * @see {@link hasNonRelevantAncestor}
+     */
+    readonly hasReadonlyAncestor: Accessor<boolean>;
+    /**
+     * A repeat instance can inherit non-relevance, just like any other node. That
+     * inheritance is derived from the repeat instance's parent node in the
+     * primary instance XML/DOM tree (and would be semantically expected to do so
+     * even if we move away from that implementation detail).
+     *
+     * Since {@link RepeatInstance.parent} is a {@link RepeatRange}, which is a
+     * runtime data model fiction that does not exist in that hierarchy, we pass
+     * this call through, allowing the {@link RepeatRange} to check the actual
+     * primary instance parent node's relevance state.
+     *
+     * @todo Should we apply similar reasoning in {@link hasReadonlyAncestor}?
+     */
+    readonly hasNonRelevantAncestor: Accessor<boolean>;
     readonly nodeType = "repeat-instance";
+    /**
+     * @see {@link RepeatRange.appearances}
+     */
+    readonly appearances: RepeatInstanceNodeAppearances;
     readonly currentState: MaterializedChildren<CurrentState<RepeatInstanceStateSpec>, GeneralChildNode>;
     constructor(parent: RepeatRange, definition: RepeatDefinition, options: RepeatInstanceOptions);
-    protected computeReference(parent: RepeatRange): string;
     protected initializeContextNode(parentContextNode: Element, nodeName: string): Element;
     subscribe(): void;
     getChildren(): readonly GeneralChildNode[];

package/dist/instance/RepeatRange.d.ts

@@ -1,10 +1,10 @@
 import { Accessor } from 'solid-js';
-import { RepeatRangeNode } from '../client/RepeatRangeNode.ts';
+import { RepeatRangeNode, RepeatRangeNodeAppearances } 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 { RepeatRangeDefinition } from '../model/RepeatRangeDefinition.ts';
 import { RepeatDefinition, RepeatInstance } from './RepeatInstance.ts';
 import { Root } from './Root.ts';
 import { DescendantNodeSharedStateSpec, DescendantNode } from './abstract/DescendantNode.ts';
@@ -21,7 +21,7 @@ interface RepeatRangeStateSpec extends DescendantNodeSharedStateSpec {
     readonly valueOptions: null;
     readonly value: null;
 }
-export declare class RepeatRange extends DescendantNode<RepeatSequenceDefinition, RepeatRangeStateSpec, RepeatInstance> implements RepeatRangeNode, EvaluationContext, SubscribableDependency {
+export declare class RepeatRange extends DescendantNode<RepeatRangeDefinition, 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
@@ -48,12 +48,91 @@ export declare class RepeatRange extends DescendantNode<RepeatSequenceDefinition
     private readonly childrenState;
     protected readonly state: SharedNodeState<RepeatRangeStateSpec>;
     protected engineState: EngineState<RepeatRangeStateSpec>;
+    /**
+     * @todo Should we special case repeat `readonly` state the same way
+     * we do for `relevant`?
+     *
+     * @see {@link isSelfRelevant}
+     */
+    isSelfReadonly: Accessor<boolean>;
+    private readonly emptyRangeEvaluationContext;
+    /**
+     * @see {@link isSelfRelevant}
+     */
+    private readonly isEmptyRangeSelfRelevant;
+    /**
+     * A repeat range does not exist in the primary instance tree. A `relevant`
+     * expression applies to each {@link RepeatInstance} child of the repeat
+     * range. Determining whether a repeat range itself "is relevant" isn't a
+     * concept the spec addresses, but it may be used by clients to determine
+     * whether to allow interaction with the range (e.g. by adding a repeat
+     * instance, or presenting the range's label when empty).
+     *
+     * As a naive first pass, it seems like the heuristic for this should be:
+     *
+     * 1. Does the repeat range have any repeat instance children?
+     *
+     *     - If yes, go to 2.
+     *     - If no, go to 3.
+     *
+     * 2. Does one or more of those children return `true` for the node's
+     *    `relevant` expression (i.e. is the repeat instance "self relevant")?
+     *
+     * 3. Does the relevant expression return `true` for the repeat range itself
+     *    (where, at least for now, the context of that evaluation would be the
+     *    repeat range's {@link anchorNode} to ensure correct relative expressions
+     *    resolve correctly)?
+     *
+     * @todo While (3) is proactively implemented, there isn't presently a test
+     * exercising it. It felt best for now to surface this for discussion in
+     * review to validate that it's going in the right direction.
+     *
+     * @todo While (2) **is actually tested**, the tests currently in place behave
+     * the same way with only the logic for (3), regardless of whether the repeat
+     * range actually has any repeat instance children. It's unclear (a) if that's
+     * a preferable simplification and (b) how that might affect performance (in
+     * theory it could vary depending on form structure and runtime state).
+     */
+    readonly isSelfRelevant: Accessor<boolean>;
     readonly nodeType = "repeat-range";
+    /**
+     * @todo RepeatRange*, RepeatInstance* (and RepeatTemplate*) all share the
+     * same body element, and thus all share the same definition `bodyElement`. As
+     * such, they also all share the same `appearances`. At time of writing,
+     * `web-forms` (Vue UI package) treats a `RepeatRangeNode`...
+     *
+     * - ... as a group, if the node has a label (i.e.
+     *   `<group><label/><repeat/></group>`)
+     * - ... effectively as a fragment containing only its instances, otherwise
+     *
+     * We now collapse `<group><repeat>` into `<repeat>`, and no longer treat
+     * "repeat group" as a concept (after parsing). According to the spec, these
+     * appearances **are supposed to** come from that "repeat group" in the form
+     * definition. In practice, many forms do define appearances directly on a
+     * repeat element. The engine currently produces an error if both are defined
+     * simultaneously, but otherwise makes no distinction between appearances in
+     * these form definition shapes:
+     *
+     * ```xml
+     * <group ref="/data/rep1" appearance="...">
+     *   <repeat nodeset="/data/rep1"/>
+     * </group>
+     *
+     * <group ref="/data/rep1">
+     *   <repeat nodeset="/data/rep1"/ appearance="...">
+     * </group>
+     *
+     * <repeat nodeset="/data/rep1"/ appearance="...">
+     * ```
+     *
+     * All of the above creates considerable ambiguity about where "repeat
+     * appearances" should apply, under which circumstances.
+     */
+    readonly appearances: RepeatRangeNodeAppearances;
     readonly currentState: MaterializedChildren<CurrentState<RepeatRangeStateSpec>, RepeatInstance>;
-    constructor(parent: GeneralParentNode, definition: RepeatSequenceDefinition);
+    constructor(parent: GeneralParentNode, definition: RepeatRangeDefinition);
     private getLastIndex;
     protected initializeContextNode(parentContextNode: Element): Element;
-    protected computeReference(parent: GeneralParentNode): string;
     getInstanceIndex(instance: RepeatInstance): number;
     addInstances(afterIndex?: number, count?: number, definition?: RepeatDefinition): Root;
     /**

package/dist/instance/Root.d.ts

@@ -1,6 +1,7 @@
 import { XFormsXPathEvaluator } from '@getodk/xpath';
 import { Accessor, Signal } from 'solid-js';
 import { XFormDOM } from '../XFormDOM.ts';
+import { BodyClassList } from '../body/BodyDefinition.ts';
 import { ActiveLanguage, FormLanguage, FormLanguages } from '../client/FormLanguage.ts';
 import { RootNode } from '../client/RootNode.ts';
 import { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
@@ -29,41 +30,25 @@ interface RootStateSpec {
     readonly activeLanguage: Signal<ActiveLanguage>;
 }
 export declare class Root extends InstanceNode<RootDefinition, RootStateSpec, GeneralChildNode> implements RootNode, EvaluationContext, EvaluationContextRoot, SubscribableDependency, TranslationContext {
-    static initialize(xformDOM: XFormDOM, definition: RootDefinition, engineConfig: InstanceConfig): Promise<Root>;
     private readonly childrenState;
+    readonly hasReadonlyAncestor: () => boolean;
+    readonly isReadonly: () => boolean;
+    readonly hasNonRelevantAncestor: () => boolean;
+    readonly isRelevant: () => boolean;
     protected readonly state: SharedNodeState<RootStateSpec>;
     protected readonly engineState: EngineState<RootStateSpec>;
     readonly nodeType = "root";
+    readonly appearances: null;
+    readonly classes: BodyClassList;
     readonly currentState: MaterializedChildren<CurrentState<RootStateSpec>, GeneralChildNode>;
     protected readonly instanceDOM: XFormDOM;
     readonly root: this;
     readonly evaluator: XFormsXPathEvaluator;
-    private readonly rootReference;
-    get contextReference(): string;
     readonly contextNode: Element;
     readonly parent: null;
     readonly languages: FormLanguages;
     get activeLanguage(): ActiveLanguage;
-    protected constructor(xformDOM: XFormDOM, definition: RootDefinition, engineConfig: InstanceConfig);
-    /**
-     * Waits until form state is fully initialized.
-     *
-     * As much as possible, all instance state computations are implemented so
-     * that they complete synchronously.
-     *
-     * There is currently one exception: because instance nodes may form
-     * computation dependencies into their descendants as well as their ancestors,
-     * there is an allowance **during form initialization only** to account for
-     * this chicken/egg scenario. Note that this allowance is intentionally,
-     * strictly limited: if form state initialization is not resolved within a
-     * single microtask tick we throw/reject.
-     *
-     * All subsequent computations are always performed synchronously (and we will
-     * use tests to validate this, by utilizing the synchronously returned `Root`
-     * state from client-facing write interfaces).
-     */
-    formStateInitialized(): Promise<void>;
-    protected computeReference(_parent: null, definition: RootDefinition): string;
+    constructor(xformDOM: XFormDOM, definition: RootDefinition, engineConfig: InstanceConfig);
     getChildren(): readonly GeneralChildNode[];
     setLanguage(language: FormLanguage): Root;
     subscribe(): void;

package/dist/instance/SelectField.d.ts

@@ -1,6 +1,6 @@
 import { Accessor } from 'solid-js';
 import { AnySelectDefinition } from '../body/control/select/SelectDefinition.ts';
-import { SelectItem, SelectNode } from '../client/SelectNode.ts';
+import { SelectItem, SelectNode, SelectNodeAppearances } from '../client/SelectNode.ts';
 import { TextRange } from '../index.ts';
 import { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
 import { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
@@ -29,13 +29,13 @@ export declare class SelectField extends DescendantNode<SelectFieldDefinition, S
     protected readonly state: SharedNodeState<SelectFieldStateSpec>;
     protected engineState: EngineState<SelectFieldStateSpec>;
     readonly nodeType = "select";
+    readonly appearances: SelectNodeAppearances;
     readonly currentState: CurrentState<SelectFieldStateSpec>;
     readonly encodeValue: (runtimeValue: readonly SelectItem[]) => string;
     readonly decodeValue: (instanceValue: string) => readonly SelectItem[];
     protected readonly getValueOptions: Accessor<readonly SelectItem[]>;
     constructor(parent: GeneralParentNode, definition: SelectFieldDefinition);
     protected getSelectItemsByValue(valueOptions?: readonly SelectItem[]): ReadonlyMap<string, SelectItem>;
-    protected computeReference(parent: GeneralParentNode): string;
     protected updateSelectedItemValues(values: readonly string[]): void;
     protected setSelectedItemValue(value: string | null): void;
     select(selectedItem: SelectItem): Root;

package/dist/instance/StringField.d.ts

@@ -1,6 +1,6 @@
 import { Accessor } from 'solid-js';
 import { InputDefinition } from '../body/control/InputDefinition.ts';
-import { StringNode } from '../client/StringNode.ts';
+import { StringNode, StringNodeAppearances } from '../client/StringNode.ts';
 import { TextRange } from '../index.ts';
 import { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
 import { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
@@ -28,11 +28,11 @@ export declare class StringField extends DescendantNode<StringFieldDefinition, S
     protected readonly state: SharedNodeState<StringFieldStateSpec>;
     protected engineState: EngineState<StringFieldStateSpec>;
     readonly nodeType = "string";
+    readonly appearances: StringNodeAppearances;
     readonly currentState: CurrentState<StringFieldStateSpec>;
     readonly encodeValue: (value: string) => string;
     readonly decodeValue: (value: string) => string;
     constructor(parent: GeneralParentNode, definition: StringFieldDefinition);
-    protected computeReference(parent: GeneralParentNode): string;
     getChildren(): readonly [];
     setValue(value: string): Root;
 }

package/dist/instance/Subtree.d.ts

@@ -22,9 +22,9 @@ export declare class Subtree extends DescendantNode<SubtreeDefinition, SubtreeSt
     protected readonly state: SharedNodeState<SubtreeStateSpec>;
     protected engineState: EngineState<SubtreeStateSpec>;
     readonly nodeType = "subtree";
+    readonly appearances: null;
     readonly currentState: MaterializedChildren<CurrentState<SubtreeStateSpec>, GeneralChildNode>;
     constructor(parent: GeneralParentNode, definition: SubtreeDefinition);
-    protected computeReference(parent: GeneralParentNode): string;
     getChildren(): readonly GeneralChildNode[];
 }
 export {};

package/dist/instance/abstract/DescendantNode.d.ts

@@ -22,16 +22,23 @@ export type DescendantNodeStateSpec<Value = never> = InstanceNodeStateSpec<Value
 export type DescendantNodeDefinition = Extract<AnyNodeDefinition, AnyDescendantNodeDefinition>;
 export type DescendantNodeParent<Definition extends DescendantNodeDefinition> = Definition extends ValueNodeDefinition ? GeneralParentNode : Definition extends RepeatInstanceDefinition ? RepeatRange : GeneralParentNode;
 export type AnyDescendantNode = DescendantNode<DescendantNodeDefinition, DescendantNodeStateSpec<any>, any>;
+interface DescendantNodeOptions {
+    readonly computeReference?: Accessor<string>;
+}
 export declare abstract class DescendantNode<Definition extends DescendantNodeDefinition, Spec extends DescendantNodeStateSpec<any>, Child extends AnyChildNode | null = null> extends InstanceNode<Definition, Spec, Child> implements BaseNode, EvaluationContext, SubscribableDependency {
     readonly parent: DescendantNodeParent<Definition>;
     readonly definition: Definition;
+    readonly hasReadonlyAncestor: Accessor<boolean>;
+    readonly isSelfReadonly: Accessor<boolean>;
+    readonly isReadonly: Accessor<boolean>;
+    readonly hasNonRelevantAncestor: Accessor<boolean>;
+    readonly isSelfRelevant: Accessor<boolean>;
+    readonly isRelevant: Accessor<boolean>;
+    protected readonly isRequired: Accessor<boolean>;
     readonly root: Root;
     readonly evaluator: XFormsXPathEvaluator;
     readonly contextNode: Element;
-    constructor(parent: DescendantNodeParent<Definition>, definition: Definition);
-    protected computeChildStepReference(parent: DescendantNodeParent<Definition>): string;
-    protected abstract computeReference(parent: DescendantNodeParent<Definition>, definition: Definition): string;
-    protected buildSharedStateSpec(parent: DescendantNodeParent<Definition>, definition: Definition): DescendantNodeSharedStateSpec;
+    constructor(parent: DescendantNodeParent<Definition>, definition: Definition, options?: DescendantNodeOptions);
     protected createContextNode(parentContextNode: Element, nodeName: string): Element;
     /**
      * Currently expected to be overridden by...
@@ -74,3 +81,4 @@ export declare abstract class DescendantNode<Definition extends DescendantNodeDe
      */
     remove(this: AnyChildNode): void;
 }
+export {};

package/dist/instance/abstract/InstanceNode.d.ts

@@ -1,6 +1,7 @@
 import { XFormsXPathEvaluator } from '@getodk/xpath';
 import { Accessor, Signal } from 'solid-js';
 import { BaseNode } from '../../client/BaseNode.ts';
+import { NodeAppearances } from '../../client/NodeAppearances.ts';
 import { InstanceNodeType } from '../../client/node-types.ts';
 import { TextRange } from '../../index.ts';
 import { CurrentState } from '../../lib/reactivity/node-state/createCurrentState.ts';
@@ -28,9 +29,6 @@ export interface InstanceNodeStateSpec<Value = never> {
     readonly value: Signal<Value> | SimpleAtomicState<Value> | null;
 }
 type AnyInstanceNode = InstanceNode<AnyNodeDefinition, InstanceNodeStateSpec<any>, any>;
-interface InitializedStateOptions<T, K extends keyof T> {
-    readonly uninitializedFallback: T[K];
-}
 /**
  * This type has the same effect as {@link MaterializedChildren}, but abstractly
  * handles leaf node types as well.
@@ -38,52 +36,52 @@ interface InitializedStateOptions<T, K extends keyof T> {
 export type InstanceNodeCurrentState<Spec extends InstanceNodeStateSpec<any>, Child> = CurrentState<Omit<Spec, 'children'>> & {
     readonly children: [Child] extends [AnyChildNode] ? readonly Child[] : null;
 };
+interface ComputableReferenceNode {
+    readonly parent: AnyParentNode | null;
+    readonly definition: AnyNodeDefinition;
+}
+type ComputeInstanceNodeReference = <This extends ComputableReferenceNode>(this: This, parent: This['parent'], definition: This['definition']) => string;
+export interface InstanceNodeOptions {
+    readonly computeReference?: () => string;
+}
 export declare abstract class InstanceNode<Definition extends AnyNodeDefinition, Spec extends InstanceNodeStateSpec<any>, Child extends AnyChildNode | null = null> implements BaseNode, EvaluationContext, SubscribableDependency {
     readonly engineConfig: InstanceConfig;
     readonly parent: AnyParentNode | null;
     readonly definition: Definition;
-    protected readonly isStateInitialized: Accessor<boolean>;
     protected abstract readonly state: SharedNodeState<Spec>;
     protected abstract readonly engineState: EngineState<Spec>;
     /**
-     * Provides a generalized mechanism for accessing a reactive state value
-     * during a node's construction, while {@link engineState} is still being
-     * defined and thus isn't assigned.
-     *
-     * The fallback value specified in {@link options} will be returned on access
-     * until {@link isStateInitialized} returns true. This ensures:
-     *
-     * - a value of the expected type will be available
-     * - any read access will become reactive to the actual state, once it has
-     *   been initialized and {@link engineState} is assigned
-     *
-     * @todo This is one among several chicken/egg problems encountered trying to
-     * support state initialization in which some aspects of the state derive from
-     * other aspects of it. It would be nice to dispense with this entirely. But
-     * if it must persist, we should also consider replacing the method with a
-     * direct accessor once state initialization completes, so the initialized
-     * check is only called until it becomes impertinent.
+     * @package Exposed on every node type to facilitate inheritance, as well as
+     * conditional behavior for value nodes.
+     */
+    abstract readonly hasReadonlyAncestor: Accessor<boolean>;
+    /**
+     * @package Exposed on every node type to facilitate inheritance, as well as
+     * conditional behavior for value nodes.
      */
-    protected getInitializedState<K extends keyof EngineState<Spec>>(key: K, options: InitializedStateOptions<EngineState<Spec>, K>): EngineState<Spec>[K];
+    abstract readonly isReadonly: Accessor<boolean>;
     /**
      * @package Exposed on every node type to facilitate inheritance, as well as
      * conditional behavior for value nodes.
      */
-    get isReadonly(): boolean;
+    abstract readonly hasNonRelevantAncestor: Accessor<boolean>;
     /**
      * @package Exposed on every node type to facilitate inheritance, as well as
      * conditional behavior for value nodes.
      */
-    get isRelevant(): boolean;
+    abstract readonly isRelevant: Accessor<boolean>;
     readonly nodeId: NodeID;
     abstract readonly nodeType: InstanceNodeType;
+    abstract readonly appearances: NodeAppearances<Definition>;
     abstract readonly currentState: InstanceNodeCurrentState<Spec, Child>;
     abstract readonly root: Root;
     abstract readonly evaluator: XFormsXPathEvaluator;
     readonly scope: ReactiveScope;
-    get contextReference(): string;
+    readonly computeReference: ComputeInstanceNodeReference;
+    protected readonly computeChildStepReference: ComputeInstanceNodeReference;
+    readonly contextReference: () => string;
     abstract readonly contextNode: Element;
-    constructor(engineConfig: InstanceConfig, parent: AnyParentNode | null, definition: Definition);
+    constructor(engineConfig: InstanceConfig, parent: AnyParentNode | null, definition: Definition, options?: InstanceNodeOptions);
     /**
      * @package This presently serves a few internal use cases, where certain
      * behaviors depend on arbitrary traversal from any point in the instance
@@ -95,9 +93,8 @@ export declare abstract class InstanceNode<Definition extends AnyNodeDefinition,
      * interface for those internal uses.
      */
     abstract getChildren(this: AnyInstanceNode): readonly AnyChildNode[];
-    protected abstract computeReference(parent: AnyInstanceNode | null, definition: Definition): string;
-    getNodeByReference(this: AnyNode, visited: WeakSet<AnyNode>, dependencyReference: string): SubscribableDependency | null;
-    getSubscribableDependencyByReference(this: AnyNode, reference: string): SubscribableDependency | null;
+    getNodesByReference(this: AnyNode, visited: WeakSet<AnyNode>, dependencyReference: string): readonly SubscribableDependency[];
+    getSubscribableDependenciesByReference(this: AnyNode, reference: string): readonly SubscribableDependency[];
     /**
      * This is a default implementation suitable for most node types. The rest
      * (currently: `Root`, `RepeatRange`, `RepeatInstance`) should likely extend

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

@@ -1,4 +1,5 @@
 import { XFormsXPathEvaluator } from '@getodk/xpath';
+import { Accessor } from 'solid-js';
 import { ReactiveScope } from '../../lib/reactivity/scope.ts';
 import { SubscribableDependency } from './SubscribableDependency.ts';
 import { TranslationContext } from './TranslationContext.ts';
@@ -25,11 +26,11 @@ export interface EvaluationContext {
      * Produces the current absolute reference to the {@link contextNode}, where
      * the absolute `/` resolves to the active form state's primary instance root.
      */
-    get contextReference(): string;
+    readonly contextReference: Accessor<string>;
     readonly contextNode: Node;
     /**
-     * Resolves a nodeset reference, possibly relative to the
-     * {@link EvaluationContext.contextNode}.
+     * Resolves nodes corresponding to the provided node-set reference, possibly
+     * relative to the {@link EvaluationContext.contextNode}.
      */
-    readonly getSubscribableDependencyByReference: (reference: string) => SubscribableDependency | null;
+    getSubscribableDependenciesByReference(reference: string): readonly SubscribableDependency[];
 }

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

@@ -15,8 +15,8 @@ export interface ValueContext<RuntimeValue> extends EvaluationContext {
     readonly scope: ReactiveScope;
     readonly definition: ValueContextDefinition;
     readonly contextNode: Element;
-    get isReadonly(): boolean;
-    get isRelevant(): boolean;
+    isReadonly(): boolean;
+    isRelevant(): boolean;
     readonly encodeValue: (this: unknown, runtimeValue: RuntimeValue) => InstanceValue;
     readonly decodeValue: (this: unknown, instanceValue: InstanceValue) => RuntimeValue;
 }

package/dist/lib/TokenListParser.d.ts

@@ -0,0 +1,84 @@
+import { PartiallyKnownString } from '../../../common/types/string/PartiallyKnownString.ts';
+
+type SymbolIterator = typeof Symbol.iterator;
+type TokenListKey<CanonicalToken extends string> = PartiallyKnownString<CanonicalToken> | SymbolIterator;
+type TokenListIterator<CanonicalToken extends string> = IterableIterator<PartiallyKnownString<CanonicalToken>>;
+/**
+ * @see {@link TokenListParser}
+ */
+export type TokenList<CanonicalToken extends string = string> = {
+    readonly [Key in TokenListKey<CanonicalToken>]: Key extends SymbolIterator ? () => TokenListIterator<CanonicalToken> : boolean;
+};
+interface TokenListAlias<CanonicalToken extends string> {
+    readonly fromAlias: string;
+    readonly toCanonical: CanonicalToken;
+}
+type TokenAliases<CanonicalToken extends string> = ReadonlyArray<TokenListAlias<CanonicalToken>>;
+interface TokenListParserOptions<CanonicalToken extends string> {
+    readonly aliases?: TokenAliases<CanonicalToken>;
+}
+type TokenListAttributeName = PartiallyKnownString<'appearance' | 'class'>;
+/**
+ * Intended primarily for use in parsing these features:
+ *
+ * - {@link https://getodk.github.io/xforms-spec/#appearances | appearances} ({@link https://xlsform.org/en/#appearance | additional documentation})
+ *
+ * - {@link https://getodk.github.io/xforms-spec/#body-attributes | body `class` attribute}
+ *
+ * This class is named as a reference to {@link DOMTokenList}
+ * ({@link https://developer.mozilla.org/en-US/docs/Web/API/DOMTokenList | MDN}),
+ * with these similarities:
+ *
+ * - Represents a value whose serialization is a space-separated list.
+ * - Each member ("token") is a string (without whitespace).
+ * - Provides set-like semantics to determine presence of members.
+ * - Provides ordering semantics as determined by the serialization.
+ *
+ * This class differs from that prior art in that:
+ *
+ * - It provides a notion of "canonical" members. This is _mostly_ (but not
+ *   entirely) intended as a convenience to client developers, automatically
+ *   populating canonical/known tokens for a given parser type in
+ *   editor-provided autocomplete, etc. **Importantly**, non-canonical tokens
+ *   _are not ignored_ in either the {@link TokenList}'s types or runtime
+ *   values.
+ *
+ * - Provided "canonical" members may also be used to specify
+ *   {@link TokenListParserOptions.aliases | optional aliases}. (Example: when
+ *   parsing "appearances", an alias might map an older deprecated appearance to
+ *   a newer canonical equivalent.) **Importantly**, when a token matches an
+ *   alias, both that alias _and the token as-specified_ will be present in the
+ *   produced {@link TokenList}.
+ *
+ * - As a parser, it is intended to be read-only. The serialized format which it
+ *   parses is _generally_ the source of truth (excepting e.g. aliases).
+ *   Notably, and as mentioned above, ordering is determined by:
+ *
+ *     - Iterating each member, as provided by the serialized representation
+ *
+ *     - If that member corresponds to an alias, that alias is yielded first
+ *
+ *     - Regardless of whether the member corresponds to an alias, the member is
+ *       yielded as-specified
+ *
+ * - A parsed {@link TokenList} is intended to maximize convenience of read-only
+ *   access. Despite many _conceptual similarities_, most of the
+ *   {@link DOMTokenList} **interface** is eschewed in favor of two (mutually
+ *   equivalent) access mechanisms:
+ *
+ *     - `Iterable<Token>`, with the ordering semantics described above
+ *     - `Record<Token, boolean>`
+ *
+ * \* This may change, as we refine requirements. In the future, we may
+ * introduce a notion of mutually exclusive tokens (e.g. "appearances" which
+ * cannot be used together), which may in turn utilize instance-defined ordering
+ * as part of that mechanism.
+ */
+export declare class TokenListParser<CanonicalToken extends string, TokenAlias extends CanonicalToken = CanonicalToken> {
+    readonly canonicalTokens: readonly CanonicalToken[];
+    private readonly aliases;
+    constructor(canonicalTokens: readonly CanonicalToken[], options?: TokenListParserOptions<TokenAlias>);
+    parseFrom(element: Element, attributeName: TokenListAttributeName): TokenList<CanonicalToken>;
+}
+export type ParsedTokenList<Parser extends TokenListParser<any>> = Parser extends TokenListParser<infer CanonicalToken> ? TokenList<CanonicalToken> : never;
+export {};

package/dist/lib/dom/query.d.ts

@@ -9,6 +9,10 @@ export interface ItemsetElement extends KnownAttributeLocalNamedElement<'itemset
 }
 export interface LabelElement extends LocalNamedElement<'label'> {
 }
+export interface RepeatGroupLabelElement extends LabelElement {
+    getAttribute(name: 'form-definition-source'): 'repeat-group';
+    getAttribute(name: string): string;
+}
 export interface RepeatElement extends KnownAttributeLocalNamedElement<'repeat', 'nodeset'> {
 }
 export interface ValueElement extends LocalNamedElement<'value'> {
@@ -17,5 +21,6 @@ export declare const getHintElement: (parent: Element) => HintElement | null;
 export declare const getItemElements: (parent: SelectElement) => readonly ItemElement[];
 export declare const getItemsetElement: (parent: Element) => ItemsetElement | null;
 export declare const getLabelElement: (parent: Element) => LabelElement | null;
+export declare const getRepeatGroupLabelElement: (parent: Element) => RepeatGroupLabelElement | null;
 export declare const getRepeatElement: (parent: Element) => RepeatElement | null;
 export declare const getValueElement: (parent: ItemElement | ItemsetElement) => ValueElement | null;

package/dist/lib/reactivity/materializeCurrentStateChildren.d.ts

@@ -1,6 +1,7 @@
 import { AnyChildNode } from '../../instance/hierarchy.ts';
 import { NodeID } from '../../instance/identity.ts';
 import { ChildrenState } from './createChildrenState.ts';
+import { ReactiveScope } from './scope.ts';
 
 export interface EncodedParentState {
     readonly children: readonly NodeID[];
@@ -16,4 +17,4 @@ export type MaterializedChildren<BaseState extends EncodedParentState, Child ext
  *
  * @see {@link createChildrenState} for further detail.
  */
-export declare const materializeCurrentStateChildren: <Child extends AnyChildNode, ParentState extends EncodedParentState>(currentState: ParentState, childrenState: ChildrenState<Child>) => MaterializedChildren<ParentState, Child>;
+export declare const materializeCurrentStateChildren: <Child extends AnyChildNode, ParentState extends EncodedParentState>(scope: ReactiveScope, currentState: ParentState, childrenState: ChildrenState<Child>) => MaterializedChildren<ParentState, Child>;

package/dist/model/DescendentNodeDefinition.d.ts

@@ -1,11 +1,10 @@
 import { AnyBodyElementDefinition } from '../body/BodyDefinition.ts';
-import { RepeatDefinition } from '../body/RepeatDefinition.ts';
 import { BindDefinition } from './BindDefinition.ts';
 import { ModelNode, NodeChildren, NodeDefaultValue, NodeDefinition, NodeDefinitionType, NodeInstances, NodeParent } from './NodeDefinition.ts';
 import { RootDefinition } from './RootDefinition.ts';
 
 export type DescendentNodeType = Exclude<NodeDefinitionType, 'root'>;
-type DescendentNodeBodyElement = AnyBodyElementDefinition | RepeatDefinition;
+type DescendentNodeBodyElement = AnyBodyElementDefinition;
 export declare abstract class DescendentNodeDefinition<Type extends DescendentNodeType, BodyElement extends DescendentNodeBodyElement | null = DescendentNodeBodyElement | null> implements NodeDefinition<Type> {
     readonly parent: NodeParent<Type>;
     readonly bind: BindDefinition;