feat(#243): Adds the rank question type

.changeset/proud-beans-march.md

@@ -0,0 +1,8 @@
+---
+'@getodk/xforms-engine': minor
+'@getodk/web-forms': minor
+'@getodk/scenario': minor
+'@getodk/common': patch
+---
+
+Support for rank question types (`<odk:rank>`)

packages/common/src/fixtures/rank/1-rank.xml

@@ -0,0 +1,146 @@
+<?xml version="1.0"?>
+<h:html xmlns="http://www.w3.org/2002/xforms" xmlns:h="http://www.w3.org/1999/xhtml"
+        xmlns:ev="http://www.w3.org/2001/xml-events" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+        xmlns:jr="http://openrosa.org/javarosa" xmlns:orx="http://openrosa.org/xforms"
+        xmlns:odk="http://www.opendatakit.org/xforms">
+  <h:head>
+    <h:title>Rank</h:title>
+    <model odk:xforms-version="1.0.0">
+      <itext>
+        <translation lang="English (en)">
+          <text id="decision_making-0">
+            <value>Health</value>
+          </text>
+          <text id="decision_making-1">
+            <value>Family and Friends</value>
+          </text>
+          <text id="decision_making-2">
+            <value>Career Growth and Learning Opportunities</value>
+          </text>
+          <text id="decision_making-3">
+            <value>Financial Stability</value>
+          </text>
+          <text id="decision_making-4">
+            <value>Pursuit of Hobbies and Passions</value>
+          </text>
+          <text id="decision_making-5">
+            <value>Environmental Sustainability</value>
+          </text>
+          <text id="decision_making-6">
+            <value>Time Management and Work-Life Balance</value>
+          </text>
+          <text id="decision_making-7">
+            <value>Building a Supportive Community</value>
+          </text>
+          <text id="decision_making-8">
+            <value>Personal Development and Mindfulness</value>
+          </text>
+          <text id="decision_making-9">
+            <value>Creativity and Innovation</value>
+          </text>
+          <text id="/data/priorities:label">
+            <value>What values guide your decision-making?</value>
+          </text>
+        </translation>
+        <translation lang="French (fr)">
+          <text id="decision_making-0">
+            <value>Santé</value>
+          </text>
+          <text id="decision_making-1">
+            <value>Famille et amis</value>
+          </text>
+          <text id="decision_making-2">
+            <value>Croissance professionnelle et opportunités d'apprentissage</value>
+          </text>
+          <text id="decision_making-3">
+            <value>Stabilité financière</value>
+          </text>
+          <text id="decision_making-4">
+            <value>Poursuite de loisirs et passions</value>
+          </text>
+          <text id="decision_making-5">
+            <value>Durabilité environnementale</value>
+          </text>
+          <text id="decision_making-6">
+            <value>Gestion du temps et équilibre vie professionnelle/vie personnelle</value>
+          </text>
+          <text id="decision_making-7">
+            <value>Construire une communauté solidaire</value>
+          </text>
+          <text id="decision_making-8">
+            <value>Développement personnel et pleine conscience</value>
+          </text>
+          <text id="decision_making-9">
+            <value>Créativité et innovation</value>
+          </text>
+          <text id="/data/priorities:label">
+            <value>Quelles valeurs guident votre prise de décision?</value>
+          </text>
+        </translation>
+      </itext>
+      <instance>
+        <data id="1_rank" version="2025011401">
+          <priorities/>
+          <meta>
+            <instanceID/>
+          </meta>
+        </data>
+      </instance>
+      <instance id="decision_making">
+        <root>
+          <item>
+            <itextId>decision_making-0</itextId>
+            <name>health</name>
+          </item>
+          <item>
+            <itextId>decision_making-1</itextId>
+            <name>family_and_friends</name>
+          </item>
+          <item>
+            <itextId>decision_making-2</itextId>
+            <name>career_growth_and_learning_opportunities</name>
+          </item>
+          <item>
+            <itextId>decision_making-3</itextId>
+            <name>financial_stability</name>
+          </item>
+          <item>
+            <itextId>decision_making-4</itextId>
+            <name>pursuit_of_hobbies_and_passions</name>
+          </item>
+          <item>
+            <itextId>decision_making-5</itextId>
+            <name>environmental_sustainability</name>
+          </item>
+          <item>
+            <itextId>decision_making-6</itextId>
+            <name>time_management_and_work_life_balance</name>
+          </item>
+          <item>
+            <itextId>decision_making-7</itextId>
+            <name>building_a_supportive_community</name>
+          </item>
+          <item>
+            <itextId>decision_making-8</itextId>
+            <name>personal_development_and_mindfulness</name>
+          </item>
+          <item>
+            <itextId>decision_making-9</itextId>
+            <name>creativity_and_innovation</name>
+          </item>
+        </root>
+      </instance>
+      <bind nodeset="/data/priorities" type="odk:rank"/>
+      <bind nodeset="/data/meta/instanceID" type="string" readonly="true()" jr:preload="uid"/>
+    </model>
+  </h:head>
+  <h:body>
+    <odk:rank ref="/data/priorities">
+      <label ref="jr:itext('/data/priorities:label')"/>
+      <itemset nodeset="randomize(instance('decision_making')/root/item)">
+        <value ref="name"/>
+        <label ref="jr:itext(itextId)"/>
+      </itemset>
+    </odk:rank>
+  </h:body>
+</h:html>

packages/common/src/fixtures/rank/2-rank-with-choice-filter.xml

@@ -0,0 +1,162 @@
+<?xml version="1.0"?>
+<h:html xmlns="http://www.w3.org/2002/xforms" xmlns:h="http://www.w3.org/1999/xhtml"
+        xmlns:ev="http://www.w3.org/2001/xml-events" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+        xmlns:jr="http://openrosa.org/javarosa" xmlns:orx="http://openrosa.org/xforms"
+        xmlns:odk="http://www.opendatakit.org/xforms">
+  <h:head>
+    <h:title>Rank with choice filter</h:title>
+    <model odk:xforms-version="1.0.0">
+      <itext>
+        <translation lang="English (en)">
+          <text id="decision_making-0">
+            <value>Health</value>
+          </text>
+          <text id="decision_making-1">
+            <value>Family and Friends</value>
+          </text>
+          <text id="decision_making-2">
+            <value>Career Growth and Learning Opportunities</value>
+          </text>
+          <text id="decision_making-3">
+            <value>Financial Stability</value>
+          </text>
+          <text id="decision_making-4">
+            <value>Pursuit of Hobbies and Passions</value>
+          </text>
+          <text id="decision_making-5">
+            <value>Environmental Sustainability</value>
+          </text>
+          <text id="decision_making-6">
+            <value>Time Management and Work-Life Balance</value>
+          </text>
+          <text id="decision_making-7">
+            <value>Building a Supportive Community</value>
+          </text>
+          <text id="decision_making-8">
+            <value>Personal Development and Mindfulness</value>
+          </text>
+          <text id="decision_making-9">
+            <value>Creativity and Innovation</value>
+          </text>
+          <text id="/data/decision_making:label">
+            <value>Choose the values that guide your decision-making</value>
+          </text>
+          <text id="/data/priorities:label">
+            <value>Please prioritize the values that guide your decision-making</value>
+          </text>
+        </translation>
+        <translation lang="French (fr)">
+          <text id="decision_making-0">
+            <value>Santé</value>
+          </text>
+          <text id="decision_making-1">
+            <value>Famille et amis</value>
+          </text>
+          <text id="decision_making-2">
+            <value>Croissance professionnelle et opportunités d'apprentissage</value>
+          </text>
+          <text id="decision_making-3">
+            <value>Stabilité financière</value>
+          </text>
+          <text id="decision_making-4">
+            <value>Poursuite de loisirs et passions</value>
+          </text>
+          <text id="decision_making-5">
+            <value>Durabilité environnementale</value>
+          </text>
+          <text id="decision_making-6">
+            <value>Gestion du temps et équilibre vie professionnelle/vie personnelle</value>
+          </text>
+          <text id="decision_making-7">
+            <value>Construire une communauté solidaire</value>
+          </text>
+          <text id="decision_making-8">
+            <value>Développement personnel et pleine conscience</value>
+          </text>
+          <text id="decision_making-9">
+            <value>Créativité et innovation</value>
+          </text>
+          <text id="/data/decision_making:label">
+            <value>Choisissez les valeurs qui guident votre prise de décision</value>
+          </text>
+          <text id="/data/priorities:label">
+            <value>Veuillez prioriser les valeurs qui guident votre prise de décision</value>
+          </text>
+        </translation>
+      </itext>
+      <instance>
+        <data id="1_rank_with_choice_filter" version="2025011401">
+          <decision_making/>
+          <priorities/>
+          <meta>
+            <instanceID/>
+          </meta>
+        </data>
+      </instance>
+      <instance id="decision_making">
+        <root>
+          <item>
+            <itextId>decision_making-0</itextId>
+            <name>health</name>
+          </item>
+          <item>
+            <itextId>decision_making-1</itextId>
+            <name>family_and_friends</name>
+          </item>
+          <item>
+            <itextId>decision_making-2</itextId>
+            <name>career_growth_and_learning_opportunities</name>
+          </item>
+          <item>
+            <itextId>decision_making-3</itextId>
+            <name>financial_stability</name>
+          </item>
+          <item>
+            <itextId>decision_making-4</itextId>
+            <name>pursuit_of_hobbies_and_passions</name>
+          </item>
+          <item>
+            <itextId>decision_making-5</itextId>
+            <name>environmental_sustainability</name>
+          </item>
+          <item>
+            <itextId>decision_making-6</itextId>
+            <name>time_management_and_work_life_balance</name>
+          </item>
+          <item>
+            <itextId>decision_making-7</itextId>
+            <name>building_a_supportive_community</name>
+          </item>
+          <item>
+            <itextId>decision_making-8</itextId>
+            <name>personal_development_and_mindfulness</name>
+          </item>
+          <item>
+            <itextId>decision_making-9</itextId>
+            <name>creativity_and_innovation</name>
+          </item>
+        </root>
+      </instance>
+      <bind nodeset="/data/decision_making" type="string" required="true()"/>
+      <bind nodeset="/data/priorities" type="odk:rank" required="true()"
+            relevant="count-selected( /data/decision_making )&gt;0"/>
+      <bind nodeset="/data/meta/instanceID" type="string" readonly="true()" jr:preload="uid"/>
+    </model>
+  </h:head>
+  <h:body>
+    <select ref="/data/decision_making">
+      <label ref="jr:itext('/data/decision_making:label')"/>
+      <itemset nodeset="instance('decision_making')/root/item">
+        <value ref="name"/>
+        <label ref="jr:itext(itextId)"/>
+      </itemset>
+    </select>
+    <odk:rank ref="/data/priorities">
+      <label ref="jr:itext('/data/priorities:label')"/>
+      <itemset nodeset="instance('decision_making')/root/item[selected( /data/decision_making , name)]">
+        <value ref="name"/>
+        <label ref="jr:itext(itextId)"/>
+      </itemset>
+    </odk:rank>
+  </h:body>
+</h:html>

packages/common/src/test/fixtures/xform-dsl/index.ts

@@ -218,6 +218,22 @@ export const proposed_selectDynamic: Proposed_selectDynamic = (
 
 export { proposed_selectDynamic as selectDynamic };
 
+export const proposed_rankDynamic = (ref: string, nodesetRef: string): XFormsElement => {
+	const value = t('value ref="value"');
+	const label = t('label ref="label"');
+
+	const itemsetAttributes = new Map<string, string>();
+	itemsetAttributes.set('nodeset', nodesetRef);
+
+	const itemset = new TagXFormsElement('itemset', itemsetAttributes, [value, label]);
+	const rankAttributes = new Map<string, string>();
+	rankAttributes.set('ref', ref);
+
+	return new TagXFormsElement('odk:rank', rankAttributes, [itemset]) as XFormsElement;
+};
+
+export { proposed_rankDynamic as rankDynamic };
+
 export const group = (ref: string, ...children: XFormsElement[]): XFormsElement => {
 	return t(`group ref="${ref}"`, ...children);
 };

packages/common/types/JSONValue.ts

@@ -11,7 +11,6 @@ export type JSONValue =
 export type JSONArray = readonly JSONValue[];
 
 // This must be an interface to avoid a circular type reference error
-// eslint-disable-next-line @typescript-eslint/consistent-indexed-object-style
 export interface JSONObject {
 	readonly [key: string]: JSONValue;
 }

packages/scenario/src/answer/RankNodeAnswer.ts

@@ -0,0 +1,19 @@
+import type { JSONValue } from '@getodk/common/types/JSONValue.ts';
+import type { RankNode } from '@getodk/xforms-engine';
+import { ValueNodeAnswer } from './ValueNodeAnswer.ts';
+
+export class RankNodeAnswer extends ValueNodeAnswer<RankNode> {
+	readonly stringValue: string;
+	readonly value: readonly string[];
+
+	constructor(node: RankNode) {
+		super(node);
+
+		this.stringValue = node.currentState.instanceValue;
+		this.value = node.currentState.value;
+	}
+
+	override inspectValue(): JSONValue {
+		return this.stringValue;
+	}
+}

packages/scenario/src/answer/RankValuesAnswer.ts

@@ -0,0 +1,21 @@
+import type { JSONValue } from '@getodk/common/types/JSONValue.ts';
+import type { RankNode } from '@getodk/xforms-engine';
+import { ComparableAnswer } from './ComparableAnswer.ts';
+
+/**
+ * Produces a value which may be **assigned** to a {@link RankNode}, e.g.
+ * as part of a test's "act" phase.
+ */
+export class RankValuesAnswer extends ComparableAnswer {
+	readonly stringValue: string;
+
+	constructor(readonly values: readonly string[]) {
+		super();
+
+		this.stringValue = values.join(' ');
+	}
+
+	override inspectValue(): JSONValue {
+		return this.values;
+	}
+}