@getodk/xforms-engine 0.1.1 → 0.3.0

package/dist/body/BodyDefinition.d.ts

@@ -1,27 +1,26 @@
 import { XFormDefinition } from '../XFormDefinition.ts';
 import { DependencyContext } from '../expression/DependencyContext.ts';
+import { ParsedTokenList, TokenListParser } from '../lib/TokenListParser.ts';
+import { RepeatElementDefinition } from './RepeatElementDefinition.ts';
 import { UnsupportedBodyElementDefinition } from './UnsupportedBodyElementDefinition.ts';
 import { InputDefinition } from './control/InputDefinition.ts';
 import { AnySelectDefinition } from './control/select/SelectDefinition.ts';
 import { LogicalGroupDefinition } from './group/LogicalGroupDefinition.ts';
 import { PresentationGroupDefinition } from './group/PresentationGroupDefinition.ts';
-import { RepeatGroupDefinition } from './group/RepeatGroupDefinition.ts';
 import { StructuralGroupDefinition } from './group/StructuralGroupDefinition.ts';
 
 export interface BodyElementParentContext {
     readonly reference: string | null;
     readonly element: Element;
 }
-type SupportedBodyElementDefinition = RepeatGroupDefinition | LogicalGroupDefinition | PresentationGroupDefinition | StructuralGroupDefinition | InputDefinition | AnySelectDefinition;
+export type ControlElementDefinition = AnySelectDefinition | InputDefinition;
+type SupportedBodyElementDefinition = RepeatElementDefinition | LogicalGroupDefinition | PresentationGroupDefinition | StructuralGroupDefinition | ControlElementDefinition;
 export type AnyBodyElementDefinition = SupportedBodyElementDefinition | UnsupportedBodyElementDefinition;
 export type BodyElementDefinitionArray = readonly AnyBodyElementDefinition[];
 export type AnyBodyElementType = AnyBodyElementDefinition['type'];
 export type AnyGroupElementDefinition = Extract<AnyBodyElementDefinition, {
     readonly type: `${string}-group`;
 }>;
-export type NonRepeatGroupElementDefinition = Exclude<AnyGroupElementDefinition, {
-    readonly type: 'repeat-group';
-}>;
 export declare const groupElementDefinition: (element: AnyBodyElementDefinition) => AnyGroupElementDefinition | null;
 export type AnyControlElementDefinition = Extract<AnyBodyElementDefinition, {
     readonly category: 'control';
@@ -37,17 +36,35 @@ declare class BodyElementMap extends Map<BodyElementReference, AnyBodyElementDef
         [k: string]: AnyBodyElementDefinition;
     };
 }
+declare const bodyClassParser: TokenListParser<"pages", "pages">;
+export type BodyClassList = ParsedTokenList<typeof bodyClassParser>;
 export declare class BodyDefinition extends DependencyContext {
     protected readonly form: XFormDefinition;
     static getChildElementDefinitions(form: XFormDefinition, parent: BodyElementParentContext, parentElement: Element, children?: readonly Element[]): readonly AnyBodyElementDefinition[];
     readonly element: Element;
+    /**
+     * @todo this class is already an oddity in that it's **like** an element
+     * definition, but it isn't one itself. Adding this property here emphasizes
+     * that awkwardness. It also extends the applicable scope where instances of
+     * this class are accessed. While it's still ephemeral, it's anticipated that
+     * this extension might cause some disomfort. If so, the most plausible
+     * alternative is an additional refactor to:
+     *
+     * 1. Introduce a `BodyElementDefinition` sublass for `<h:body>`.
+     * 2. Disambiguate the respective names of those, in some reasonable way.
+     * 3. Add a layer of indirection between this class and that new body element
+     *    definition's class.
+     * 4. At that point, we may as well prioritize the little bit of grunt work to
+     *    pass the `BodyDefinition` instance by reference rather than assigning it
+     *    to anything.
+     */
+    readonly classes: BodyClassList;
     readonly elements: readonly AnyBodyElementDefinition[];
     protected readonly elementsByReference: BodyElementMap;
     readonly parentReference: null;
     readonly reference: string;
     constructor(form: XFormDefinition);
     getBodyElement(reference: string): AnyBodyElementDefinition | null;
-    getRepeatGroup(reference: string): RepeatGroupDefinition | null;
-    toJSON(): Omit<this, "toJSON" | "form" | "isTranslated" | "registerDependentExpression" | "dependencyExpressions" | "getBodyElement" | "getRepeatGroup">;
+    toJSON(): Omit<this, "toJSON" | "form" | "isTranslated" | "registerDependentExpression" | "dependencyExpressions" | "getBodyElement">;
 }
 export {};

package/dist/body/BodyElementDefinition.d.ts

@@ -1,8 +1,9 @@
 import { XFormDefinition } from '../XFormDefinition.ts';
 import { DependencyContext } from '../expression/DependencyContext.ts';
+import { HintDefinition } from '../parse/text/HintDefinition.ts';
+import { ItemLabelDefinition } from '../parse/text/ItemLabelDefinition.ts';
+import { LabelDefinition } from '../parse/text/LabelDefinition.ts';
 import { BodyElementParentContext } from './BodyDefinition.ts';
-import { HintDefinition } from './text/HintDefinition.ts';
-import { LabelDefinition } from './text/LabelDefinition.ts';
 
 /**
  * These category names roughly correspond to each of the ODK XForms spec's
@@ -18,7 +19,7 @@ export declare abstract class BodyElementDefinition<Type extends string> extends
     abstract readonly category: BodyElementCategory;
     abstract readonly type: Type;
     readonly hint: HintDefinition | null;
-    readonly label: LabelDefinition | null;
+    readonly label: ItemLabelDefinition | LabelDefinition | null;
     readonly reference: string | null;
     readonly parentReference: string | null;
     protected constructor(form: XFormDefinition, parent: BodyElementParentContext, element: Element);

package/dist/body/RepeatElementDefinition.d.ts

@@ -0,0 +1,19 @@
+import { XFormDefinition } from '../XFormDefinition.ts';
+import { LabelDefinition } from '../parse/text/LabelDefinition.ts';
+import { BodyElementDefinitionArray, BodyElementParentContext } from './BodyDefinition.ts';
+import { BodyElementDefinition } from './BodyElementDefinition.ts';
+import { StructureElementAppearanceDefinition } from './appearance/structureElementAppearanceParser.ts';
+
+export declare class RepeatElementDefinition extends BodyElementDefinition<'repeat'> {
+    static isCompatible(localName: string): boolean;
+    readonly category = "structure";
+    readonly type = "repeat";
+    readonly reference: string;
+    readonly appearances: StructureElementAppearanceDefinition;
+    readonly label: LabelDefinition | null;
+    readonly countExpression: string | null;
+    readonly noAddRemoveExpression: string | null;
+    readonly children: BodyElementDefinitionArray;
+    constructor(form: XFormDefinition, parent: BodyElementParentContext, element: Element);
+    toJSON(): Omit<this, "toJSON" | "form" | "parent" | "isTranslated" | "registerDependentExpression" | "dependencyExpressions">;
+}

package/dist/body/appearance/inputAppearanceParser.d.ts

@@ -0,0 +1,4 @@
+import { TokenListParser, ParsedTokenList } from '../../lib/TokenListParser.ts';
+
+export declare const inputAppearanceParser: TokenListParser<"multiline" | "numbers" | "url" | "thousand-sep" | "no-calendar" | "month-year" | "year" | "ethiopian" | "coptic" | "islamic" | "bikram-sambat" | "myanmar" | "persian" | "placement-map" | "maps" | "hidden-answer" | "annotate" | "draw" | "signature" | "new-front" | "new" | "front" | "printer" | "masked", "multiline" | "numbers" | "url" | "thousand-sep" | "no-calendar" | "month-year" | "year" | "ethiopian" | "coptic" | "islamic" | "bikram-sambat" | "myanmar" | "persian" | "placement-map" | "maps" | "hidden-answer" | "annotate" | "draw" | "signature" | "new-front" | "new" | "front" | "printer" | "masked">;
+export type InputAppearanceDefinition = ParsedTokenList<typeof inputAppearanceParser>;

package/dist/body/appearance/selectAppearanceParser.d.ts

@@ -0,0 +1,4 @@
+import { TokenListParser, ParsedTokenList } from '../../lib/TokenListParser.ts';
+
+export declare const selectAppearanceParser: TokenListParser<"map" | "label" | "compact" | "horizontal" | "horizontal-compact" | "list-nolabel" | "minimal" | "columns" | "columns-1" | "columns-2" | "columns-3" | "columns-4" | "columns-5" | "columns-pack" | "autocomplete" | "likert" | "quick" | "quickcompact", "autocomplete">;
+export type SelectAppearanceDefinition = ParsedTokenList<typeof selectAppearanceParser>;

package/dist/body/appearance/structureElementAppearanceParser.d.ts

@@ -0,0 +1,4 @@
+import { TokenListParser, ParsedTokenList } from '../../lib/TokenListParser.ts';
+
+export declare const structureElementAppearanceParser: TokenListParser<"field-list" | "table-list", "field-list" | "table-list">;
+export type StructureElementAppearanceDefinition = ParsedTokenList<typeof structureElementAppearanceParser>;

package/dist/body/control/ControlDefinition.d.ts

@@ -1,8 +1,9 @@
 import { XFormDefinition } from '../../XFormDefinition.ts';
+import { ParsedTokenList } from '../../lib/TokenListParser.ts';
+import { HintDefinition } from '../../parse/text/HintDefinition.ts';
+import { LabelDefinition } from '../../parse/text/LabelDefinition.ts';
 import { BodyElementParentContext } from '../BodyDefinition.ts';
 import { BodyElementDefinition } from '../BodyElementDefinition.ts';
-import { HintDefinition } from '../text/HintDefinition.ts';
-import { LabelDefinition } from '../text/LabelDefinition.ts';
 
 type ControlType = 'input' | 'range' | 'rank' | 'select' | 'select1' | 'trigger' | 'upload';
 export declare abstract class ControlDefinition<Type extends ControlType> extends BodyElementDefinition<Type> {
@@ -11,6 +12,7 @@ export declare abstract class ControlDefinition<Type extends ControlType> extend
     readonly reference: string;
     readonly label: LabelDefinition | null;
     readonly hint: HintDefinition | null;
+    abstract readonly appearances: ParsedTokenList<any>;
     constructor(form: XFormDefinition, parent: BodyElementParentContext, element: Element);
 }
 export type AnyControlDefinition = ControlDefinition<any>;

package/dist/body/control/InputDefinition.d.ts

@@ -1,6 +1,11 @@
+import { XFormDefinition } from '../../XFormDefinition.ts';
+import { BodyElementParentContext } from '../BodyDefinition.ts';
+import { InputAppearanceDefinition } from '../appearance/inputAppearanceParser.ts';
 import { ControlDefinition } from './ControlDefinition.ts';
 
 export declare class InputDefinition extends ControlDefinition<'input'> {
     static isCompatible(localName: string): boolean;
     readonly type = "input";
+    readonly appearances: InputAppearanceDefinition;
+    constructor(form: XFormDefinition, parent: BodyElementParentContext, element: Element);
 }

package/dist/body/control/select/ItemDefinition.d.ts

@@ -1,14 +1,14 @@
 import { ItemElement } from '../../../lib/dom/query.ts';
+import { ItemLabelDefinition } from '../../../parse/text/ItemLabelDefinition.ts';
 import { XFormDefinition } from '../../../XFormDefinition.ts';
 import { BodyElementDefinition } from '../../BodyElementDefinition.ts';
-import { LabelDefinition } from '../../text/LabelDefinition.ts';
 import { AnySelectDefinition } from './SelectDefinition.ts';
 
 export declare class ItemDefinition extends BodyElementDefinition<'item'> {
     readonly parent: AnySelectDefinition;
     readonly category = "support";
     readonly type = "item";
-    readonly label: LabelDefinition | null;
+    readonly label: ItemLabelDefinition | null;
     readonly value: string;
     constructor(form: XFormDefinition, parent: AnySelectDefinition, element: ItemElement);
 }

package/dist/body/control/select/ItemsetDefinition.d.ts

@@ -1,17 +1,18 @@
-import { ItemsetElement } from '../../../lib/dom/query.ts';
 import { XFormDefinition } from '../../../XFormDefinition.ts';
+import { ItemsetElement } from '../../../lib/dom/query.ts';
+import { ItemsetLabelDefinition } from '../../../parse/text/ItemsetLabelDefinition.ts';
 import { BodyElementDefinition } from '../../BodyElementDefinition.ts';
-import { LabelDefinition } from '../../text/LabelDefinition.ts';
 import { ItemsetNodesetExpression } from './ItemsetNodesetExpression.ts';
 import { ItemsetValueExpression } from './ItemsetValueExpression.ts';
 import { AnySelectDefinition } from './SelectDefinition.ts';
 
 export declare class ItemsetDefinition extends BodyElementDefinition<'itemset'> {
+    readonly parent: AnySelectDefinition;
     readonly category = "support";
     readonly type = "itemset";
     readonly reference: string;
-    readonly label: LabelDefinition | null;
+    readonly label: ItemsetLabelDefinition | null;
     readonly nodes: ItemsetNodesetExpression;
     readonly value: ItemsetValueExpression;
-    constructor(form: XFormDefinition, select: AnySelectDefinition, element: ItemsetElement);
+    constructor(form: XFormDefinition, parent: AnySelectDefinition, element: ItemsetElement);
 }

package/dist/body/control/select/SelectDefinition.d.ts

@@ -2,11 +2,20 @@ import { CollectionValues } from '../../../../../common/types/collections/Collec
 import { LocalNamedElement } from '../../../../../common/types/dom.ts';
 import { XFormDefinition } from '../../../XFormDefinition.ts';
 import { AnyBodyElementDefinition, BodyElementParentContext } from '../../BodyDefinition.ts';
+import { SelectAppearanceDefinition } from '../../appearance/selectAppearanceParser.ts';
 import { ControlDefinition } from '../ControlDefinition.ts';
 import { ItemDefinition } from './ItemDefinition.ts';
 import { ItemsetDefinition } from './ItemsetDefinition.ts';
 
-declare const selectLocalNames: Set<"select" | "rank" | "select1">;
+/**
+ * @todo We were previously a bit overzealous about introducing `<rank>` support
+ * here. It'll likely still fit, but we should approach it with more intention.
+ *
+ * @todo `<trigger>` is *almost* reasonable to support here too. The main
+ * hesitation is that its single, implicit "item" does not have a distinct
+ * <label>, and presumably has different UX **and translation** considerations.
+ */
+declare const selectLocalNames: Set<"select" | "select1">;
 export type SelectType = CollectionValues<typeof selectLocalNames>;
 export interface SelectElement extends LocalNamedElement<SelectType> {
 }
@@ -15,6 +24,7 @@ export declare class SelectDefinition<Type extends SelectType> extends ControlDe
     static isSelect(element: AnyBodyElementDefinition): element is AnySelectDefinition;
     readonly type: Type;
     readonly element: SelectElement;
+    readonly appearances: SelectAppearanceDefinition;
     readonly itemset: ItemsetDefinition | null;
     readonly items: readonly ItemDefinition[];
     constructor(form: XFormDefinition, parent: BodyElementParentContext, element: Element);

package/dist/body/group/BaseGroupDefinition.d.ts

@@ -1,7 +1,8 @@
 import { XFormDefinition } from '../../XFormDefinition.ts';
+import { LabelDefinition } from '../../parse/text/LabelDefinition.ts';
 import { BodyElementDefinitionArray, BodyElementParentContext } from '../BodyDefinition.ts';
 import { BodyElementDefinition } from '../BodyElementDefinition.ts';
-import { LabelDefinition } from '../text/LabelDefinition.ts';
+import { StructureElementAppearanceDefinition } from '../appearance/structureElementAppearanceParser.ts';
 
 /**
  * These type names are derived from **and expand upon** the language used in
@@ -16,10 +17,6 @@ import { LabelDefinition } from '../text/LabelDefinition.ts';
  * - `presentation-group` is a group with a `<label>` child; its usage here
  *   differs from the spec language in that `presentation-group` does **not**
  *   have a `ref`
- * - `repeat-group` is not mentioned by the spec; it is an extension of
- *   `logical-group`, wherein its `ref` is the same as its immediate `<repeat>`
- *   child's `nodeset` (usage of each attribute is normalized during
- *   initialization, in {@link XFormDOM})
  * - `structural-group` is any `<group>` element which does not satisfy any of
  *   the other usage scenarios; this isn't exactly the terminology used, but is
  *   the most closely fitting name for the concept where the other sceanarios
@@ -27,21 +24,19 @@ import { LabelDefinition } from '../text/LabelDefinition.ts';
  *
  * A more succinct decision tree:
  *
- * - `<group ref="$ref"><repeat nodeset="$ref">` -> `repeat-group`, else
  * - `<group ref="$ref">` -> `logical-group`, else
  * - `<group><label>` -> `presentation-group`, else
  * - `<group>` -> `structural-group`
  */
-export type GroupType = 'logical-group' | 'presentation-group' | 'repeat-group' | 'structural-group';
+export type GroupType = 'logical-group' | 'presentation-group' | 'structural-group';
 export declare abstract class BaseGroupDefinition<Type extends GroupType> extends BodyElementDefinition<Type> {
     private static groupTypes;
     protected static getGroupType(localName: string, element: Element): GroupType | null;
     readonly category = "structure";
     readonly children: BodyElementDefinitionArray;
     readonly reference: string | null;
+    readonly appearances: StructureElementAppearanceDefinition;
     readonly label: LabelDefinition | null;
     constructor(form: XFormDefinition, parent: BodyElementParentContext, element: Element, children?: BodyElementDefinitionArray);
     getChildren(element: Element): BodyElementDefinitionArray;
 }
-export declare const repeatGroup: <T extends BaseGroupDefinition<any>>(groupDefinition: T) => Extract<T, BaseGroupDefinition<'repeat-group'>> | null;
-export declare const nonRepeatGroup: <T extends BaseGroupDefinition<any>>(groupDefinition: T) => Exclude<T, BaseGroupDefinition<'repeat-group'>> | null;

package/dist/body/group/PresentationGroupDefinition.d.ts

@@ -1,6 +1,6 @@
 import { XFormDefinition } from '../../XFormDefinition.ts';
+import { LabelDefinition } from '../../parse/text/LabelDefinition.ts';
 import { BodyElementParentContext } from '../BodyDefinition.ts';
-import { LabelDefinition } from '../text/LabelDefinition.ts';
 import { BaseGroupDefinition } from './BaseGroupDefinition.ts';
 
 export declare class PresentationGroupDefinition extends BaseGroupDefinition<'presentation-group'> {

package/dist/client/BaseNode.d.ts

@@ -1,6 +1,8 @@
 import { AnyNodeDefinition } from '../model/NodeDefinition.ts';
-import { InstanceNodeType } from './node-types.js';
+import { NodeAppearances } from './NodeAppearances.ts';
 import { TextRange } from './TextRange.ts';
+import { InstanceNodeType } from './node-types.ts';
+import { NodeValidationState } from './validation.ts';
 
 export interface BaseNodeState {
     /**
@@ -37,6 +39,17 @@ export interface BaseNodeState {
      * {@link BaseNode.parent | parent node}.
      */
     get relevant(): boolean;
+    /**
+     * Specifies whether the node must have a non-blank value to be valid (see
+     * {@link value} for details).
+     *
+     * @see {@link https://getodk.github.io/xforms-spec/#bind-attributes}
+     *
+     * @default false
+     *
+     * @todo What is the expected behavior of `required` expressions defined for
+     * non-leaf/value nodes?
+     */
     get required(): boolean;
     /**
      * Interfaces for nodes which cannot provide a label should override this to
@@ -90,6 +103,14 @@ export interface BaseNodeState {
      *
      * Parent nodes, i.e. nodes which can contain {@link children}, do not store a
      * value state. For those nodes, their value state should always be `null`.
+     *
+     * A node's value is considered "blank" when its primary instance state is an
+     * empty string, and it is considered "non-blank" otherwise. The engine may
+     * represent node values according to aspects of the node's definition (such
+     * as its defined data type, its associated control type if any). The node's
+     * value being blank or non-blank may contribute to satisfying conditions of
+     * the node's validity ({@link constraint}, {@link required}). Otherwise, it
+     * is an internal engine consideration.
      */
     get value(): unknown;
 }
@@ -108,6 +129,10 @@ export interface BaseNode {
      * the lifetime of an active session filling a form.
      */
     readonly nodeId: FormNodeID;
+    /**
+     * @see {@link TokenListParser} for details.
+     */
+    readonly appearances: NodeAppearances<any> | null;
     /**
      * Each node has a definition which specifies aspects of the node defined in
      * the form. These aspects include (but are not limited to) the node's data
@@ -131,9 +156,55 @@ export interface BaseNode {
      */
     readonly parent: BaseNode | null;
     /**
-     * Each node provides a discrete object representing the stateful aspects of
-     * that node which will change over time. When a client provides a {@link OpaqueReactiveObjectFactory}
+     * Each node provides a discrete object representing the stateful aspects\* of
+     * that node which will change over time. When a client provides a
+     * {@link OpaqueReactiveObjectFactory}, the engine will update the properties
+     * of this object as their respective states change, so a client can implement
+     * reactive updates that respond to changes as they occur.
+     *
+     * \* This includes state which is either client-/user-mutable, or state which
+     *    is computed based on the core XForms computation model. Each node also
+     *    exposes {@link validationState}, which reflects the validity of the
+     *    node, or its descendants.
      */
     readonly currentState: BaseNodeState;
+    /**
+     * Represents the validation state of a the node itself, or its descendants.
+     *
+     * @see {@link AncestorNodeValidationState} and
+     * {@link LeafNodeValidationState} for additional details.
+     *
+     * While filling a form (i.e. prior to submission), validation state can be
+     * viewed as computed metadata about the form state. The validation conditions
+     * and their violation messages produced by a node _may be computed on
+     * demand_. Clients should assume:
+     *
+     * 1. Validation state **will be current** when directly read by the client.
+     *    Accessing validation state _may_ invoke engine computation of that state
+     *    _at that time_.
+     *
+     *    It **may** also be pre-computed by the engine so that direct reads are
+     *    less computationally expensive, but such optimizations cannot be
+     *    guaranteed by the engine at this time.
+     *
+     * 2. For clients providing an {@link OpaqueReactiveObjectFactory}, accessing
+     *    validation state within a reactive context **will produce updates** to
+     *    the validation state, as long as the client retains a subscription to
+     *    that state.
+     *
+     *    If it is possible to detect interruption of such client- reactive
+     *    subscriptions, the engine _may defer computations_ until subsequent
+     *    client read/re-subscription, in order to reduce unnecessary
+     *    computational overhead. Again, such optimizations cannot be guaranteed
+     *    by the engine at this time.
+     *
+     * @todo it's easier to conceive a reliable, general solution to optimizing
+     * the direct read case, than it is for the client-reactive case (largely
+     * because our solution for client reactivity is intentionally opaque). If it
+     * turns out that such optimizations are crucial for overall usability, the
+     * client-reactive case may best be served by additional APIs for reactive
+     * clients to explicitly pause and resume recomputation.
+     */
+    readonly validationState: NodeValidationState;
 }
 export {};

package/dist/client/GroupNode.d.ts

@@ -1,8 +1,10 @@
-import { NonRepeatGroupElementDefinition } from '../body/BodyDefinition.ts';
+import { AnyGroupElementDefinition } from '../body/BodyDefinition.ts';
 import { SubtreeDefinition } from '../model/SubtreeDefinition.ts';
 import { BaseNode, BaseNodeState } from './BaseNode.ts';
+import { NodeAppearances } from './NodeAppearances.ts';
 import { RootNode } from './RootNode.ts';
 import { GeneralChildNode, GeneralParentNode } from './hierarchy.ts';
+import { AncestorNodeValidationState } from './validation.ts';
 
 export interface GroupNodeState extends BaseNodeState {
     get hint(): null;
@@ -11,15 +13,18 @@ export interface GroupNodeState extends BaseNodeState {
     get value(): null;
 }
 export interface GroupDefinition extends SubtreeDefinition {
-    readonly bodyElement: NonRepeatGroupElementDefinition;
+    readonly bodyElement: AnyGroupElementDefinition;
 }
+export type GroupNodeAppearances = NodeAppearances<GroupDefinition>;
 /**
  * A node corresponding to an XForms `<group>`.
  */
 export interface GroupNode extends BaseNode {
     readonly nodeType: 'group';
+    readonly appearances: GroupNodeAppearances;
     readonly definition: GroupDefinition;
     readonly root: RootNode;
     readonly parent: GeneralParentNode;
     readonly currentState: GroupNodeState;
+    readonly validationState: AncestorNodeValidationState;
 }

package/dist/client/ModelValueNode.d.ts

@@ -0,0 +1,37 @@
+import { LeafNodeDefinition } from '../model/LeafNodeDefinition.ts';
+import { BaseNode, BaseNodeState } from './BaseNode.ts';
+import { GeneralParentNode } from './hierarchy.ts';
+import { RootNode } from './RootNode.ts';
+import { LeafNodeValidationState } from './validation.ts';
+
+export interface ModelValueNodeState extends BaseNodeState {
+    get label(): null;
+    get hint(): null;
+    get children(): null;
+    get valueOptions(): null;
+    /**
+     * Reflects the current value of a {@link ModelValueNode}. This value may be
+     * populated when a form is loaded, and it may be updated by certain
+     * computations defined by the form.
+     */
+    get value(): string;
+}
+export interface ModelValueDefinition extends LeafNodeDefinition {
+    readonly bodyElement: null;
+}
+/**
+ * A node which is:
+ *
+ * - model-only (i.e. it has no corresponding body element)
+ * - a leaf/value node (i.e. it has no element children; it may be defined in
+ *   the form's `<model>` as either an {@link Element} or {@link Attr})
+ */
+export interface ModelValueNode extends BaseNode {
+    readonly nodeType: 'model-value';
+    readonly appearances: null;
+    readonly definition: ModelValueDefinition;
+    readonly root: RootNode;
+    readonly parent: GeneralParentNode;
+    readonly currentState: ModelValueNodeState;
+    readonly validationState: LeafNodeValidationState;
+}

package/dist/client/NodeAppearances.d.ts

@@ -0,0 +1,15 @@
+import { ParsedTokenList } from '../lib/TokenListParser.ts';
+import { NodeDefinition } from '../model/NodeDefinition.ts';
+
+/**
+ * - Provides a means to distinguish between internal and client-facing names
+ *   for the same {@link ParsedTokenList} types.
+ *
+ * - Anticipates some iteration on both parsed ("definition") types and
+ *   client-facing node types, which may not happen in tandem.
+ */
+export type NodeAppearances<Definition extends NodeDefinition<any>> = Definition extends {
+    readonly bodyElement: {
+        readonly appearances: infer Appearances extends ParsedTokenList<any>;
+    };
+} ? Appearances : null;

package/dist/client/NoteNode.d.ts

@@ -0,0 +1,53 @@
+import { InputDefinition } from '../body/control/InputDefinition.ts';
+import { LeafNodeDefinition } from '../model/LeafNodeDefinition.ts';
+import { BaseNode, BaseNodeState } from './BaseNode.ts';
+import { GeneralParentNode } from './hierarchy.ts';
+import { NodeAppearances } from './NodeAppearances.ts';
+import { RootNode } from './RootNode.ts';
+import { TextRange } from './TextRange.ts';
+import { LeafNodeValidationState } from './validation.ts';
+
+export interface NoteNodeState extends BaseNodeState {
+    /**
+     * Note-specific specialization: a note will always have a non-null value in
+     * at least one of:
+     *
+     * - {@link label}
+     * - {@link hint}
+     *
+     * This is an alias to whichever is present, with precedent to {@link label}
+     * if both are present.
+     */
+    get noteText(): NonNullable<this['label'] | this['hint']>;
+    /**
+     * A note will **always** be `readonly`.
+     */
+    readonly readonly: true;
+    get label(): TextRange<'label', 'form'> | null;
+    get hint(): TextRange<'hint', 'form'> | null;
+    get children(): null;
+    get valueOptions(): null;
+    /**
+     * Reflects the readonly value of a {@link NoteNode}, or `null` if blank.
+     */
+    get value(): string | null;
+}
+export interface NoteDefinition extends LeafNodeDefinition {
+    readonly bodyElement: InputDefinition;
+}
+export type NoteNodeAppearances = NodeAppearances<NoteDefinition>;
+/**
+ * A node which is:
+ *
+ * - associated with an input, with at least one text element (label or hint)
+ * - guaranteed to be {@link NoteNodeState.readonly | readonly}
+ */
+export interface NoteNode extends BaseNode {
+    readonly nodeType: 'note';
+    readonly appearances: NoteNodeAppearances;
+    readonly definition: NoteDefinition;
+    readonly root: RootNode;
+    readonly parent: GeneralParentNode;
+    readonly currentState: NoteNodeState;
+    readonly validationState: LeafNodeValidationState;
+}

package/dist/client/RootNode.d.ts

@@ -1,7 +1,9 @@
+import { BodyClassList } from '../body/BodyDefinition.ts';
 import { RootDefinition } from '../model/RootDefinition.ts';
 import { BaseNode, BaseNodeState } from './BaseNode.ts';
 import { ActiveLanguage, FormLanguage, FormLanguages } from './FormLanguage.ts';
 import { GeneralChildNode } from './hierarchy.ts';
+import { AncestorNodeValidationState } from './validation.ts';
 
 export interface RootNodeState extends BaseNodeState {
     /**
@@ -19,10 +21,29 @@ export interface RootNodeState extends BaseNodeState {
 }
 export interface RootNode extends BaseNode {
     readonly nodeType: 'root';
+    /**
+     * @todo this along with {@link classes} is... awkward.
+     */
+    readonly appearances: null;
+    /**
+     * @todo This is another odd deviation in {@link RootNode}. Unlike
+     * {@link languages}, it doesn't feel particularly **essential**. While it
+     * would deviate from XForms spec terminology, it seems like it _might be
+     * reasonable_ to instead convey `<h:body class="...">` as
+     * {@link RootNode.appearances} in the client interface. They do have slightly
+     * different spec semantics (i.e. a body class can be anything, to trigger
+     * styling in a form UI). But the **most likely anticipated** use case in Web
+     * Forms would be the "pages" class, and perhaps "theme-grid". The former is
+     * definitely conceptually similar to a XForms `appearance` (albeit
+     * form-global, which is not a spec concept). The latter does as well, and we
+     * already anticipate applying that concept in non-form-global ways.
+     */
+    readonly classes: BodyClassList;
     readonly definition: RootDefinition;
     readonly root: RootNode;
     readonly parent: null;
     readonly currentState: RootNodeState;
+    readonly validationState: AncestorNodeValidationState;
     /**
      * @todo as with {@link RootNodeState.activeLanguage}, this is the most
      * significant break in consistency across node types.

package/dist/client/SelectNode.d.ts

@@ -1,13 +1,15 @@
 import { AnySelectDefinition } from '../body/control/select/SelectDefinition.ts';
-import { ValueNodeDefinition } from '../model/ValueNodeDefinition.ts';
+import { LeafNodeDefinition } from '../model/LeafNodeDefinition.ts';
 import { BaseNode, BaseNodeState } from './BaseNode.ts';
+import { NodeAppearances } from './NodeAppearances.ts';
 import { RootNode } from './RootNode.ts';
 import { TextRange } from './TextRange.ts';
 import { GeneralParentNode } from './hierarchy.ts';
+import { LeafNodeValidationState } from './validation.ts';
 
 export interface SelectItem {
     get value(): string;
-    get label(): TextRange<'label'> | null;
+    get label(): TextRange<'item-label'> | null;
 }
 export interface SelectNodeState extends BaseNodeState {
     get children(): null;
@@ -29,15 +31,18 @@ export interface SelectNodeState extends BaseNodeState {
      */
     get value(): readonly SelectItem[];
 }
-export interface SelectDefinition extends ValueNodeDefinition {
+export interface SelectDefinition extends LeafNodeDefinition {
     readonly bodyElement: AnySelectDefinition;
 }
+export type SelectNodeAppearances = NodeAppearances<SelectDefinition>;
 export interface SelectNode extends BaseNode {
     readonly nodeType: 'select';
+    readonly appearances: SelectNodeAppearances;
     readonly definition: SelectDefinition;
     readonly root: RootNode;
     readonly parent: GeneralParentNode;
     readonly currentState: SelectNodeState;
+    readonly validationState: LeafNodeValidationState;
     /**
      * For use by a client to update the selection of a select node where:
      *