From 608ab4d7f136b3ce64a5662ce6cce9facdbe0d66 Mon Sep 17 00:00:00 2001
From: spwoodcock <sam.woodcock@protonmail.com>
Date: Mon, 10 Mar 2025 09:55:44 +0000
Subject: [PATCH 1/4] feat(FormGroup): make underlying FormPanel toggleable
 prop user configurable

---
 .../web-forms/src/components/FormGroup.vue    |  6 +++--
 .../web-forms/src/components/FormPanel.vue    | 26 +++++++++++++++----
 .../web-forms/src/components/QuestionList.vue |  2 +-
 3 files changed, 26 insertions(+), 8 deletions(-)

diff --git a/packages/web-forms/src/components/FormGroup.vue b/packages/web-forms/src/components/FormGroup.vue
index 968ae5592..3537c1885 100644
--- a/packages/web-forms/src/components/FormGroup.vue
+++ b/packages/web-forms/src/components/FormGroup.vue
@@ -4,7 +4,9 @@ import { computed } from 'vue';
 import FormPanel from './FormPanel.vue';
 import QuestionList from './QuestionList.vue';
 
-const props = defineProps<{ node: GroupNode }>();
+const props = withDefaults(defineProps<{ node: GroupNode, toggleable?: boolean }>(), {
+	toggleable: false,
+});
 
 const classes = ['group'];
 
@@ -18,7 +20,7 @@ const tableLayout = computed(() => {
 </script>
 
 <template>
-	<FormPanel :title="node.currentState.label?.asString" :no-ui="!node.currentState.label" :class="classes">
+	<FormPanel :title="node.currentState.label?.asString" :no-ui="!node.currentState.label" :toggleable="props.toggleable" :class="classes">
 		<div :class="{ 'table-layout': tableLayout, 'gap-2': !tableLayout, 'flex': true, 'flex-column': true }">
 			<QuestionList :nodes="node.currentState.children" />
 		</div>
diff --git a/packages/web-forms/src/components/FormPanel.vue b/packages/web-forms/src/components/FormPanel.vue
index f673a5e04..5396b5639 100644
--- a/packages/web-forms/src/components/FormPanel.vue
+++ b/packages/web-forms/src/components/FormPanel.vue
@@ -12,6 +12,7 @@ export interface PanelProps {
 	class?: string[] | string;
 	labelIcon?: string;
 	labelNumber?: number;
+    toggleable?: boolean;
 }
 
 const props = withDefaults(defineProps<PanelProps>(), {
@@ -21,6 +22,7 @@ const props = withDefaults(defineProps<PanelProps>(), {
 	class: undefined,
 	labelIcon: undefined,
 	labelNumber: undefined,
+    toggleable: false,
 });
 
 const panelClass = computed(() => [
@@ -31,7 +33,9 @@ const panelClass = computed(() => [
 const panelState = ref(false);
 
 const toggle = () => {
-	panelState.value = !panelState.value;
+    if (props.toggleable) {
+		panelState.value = !panelState.value;
+    }
 };
 
 const menu = ref<Menu & MenuState>();
@@ -40,10 +44,11 @@ const toggleMenu = (event: Event) => {
 	menu.value?.toggle(event);
 };
 </script>
+
 <template>
-	<Panel v-if="!noUi" :class="panelClass" :toggleable="true" :collapsed="panelState">
+    <Panel v-if="!noUi" :class="[panelClass, { 'toggleable-enabled': toggleable }]" :toggleable="toggleable" :collapsed="toggleable ? panelState : false">
 		<template #header>
-			<div class="panel-title" role="button" @click="toggle">
+            <div v-if="toggleable" class="panel-title" role="button" @click="toggle">
 				<h2>
 					<span class="chevron" :class="panelState ? 'icon-keyboard_arrow_down' : 'icon-keyboard_arrow_up'" />
 					<span v-if="labelNumber" class="label-number">{{ labelNumber }}</span>
@@ -51,6 +56,13 @@ const toggleMenu = (event: Event) => {
 					<span v-if="labelIcon" class="ml-2" :class="labelIcon" />
 				</h2>
 			</div>
+            <div v-else>
+                <h2>
+                    <span v-if="labelNumber" class="label-number">{{ labelNumber }}</span>
+                    <span>{{ title }}</span>
+                    <span v-if="labelIcon" class="ml-2" :class="labelIcon" />
+                </h2>
+            </div>
 		</template>
 		<template v-if="menuItems && menuItems.length > 0" #icons>
 			<Button severity="secondary" rounded class="btn-context" :class="{ 'p-focus': menu?.overlayVisible }" icon="icon-more_vert" aria-label="More" @click="toggleMenu" />
@@ -129,9 +141,8 @@ h2 {
 	}
 
 	:deep(.p-panel-content) {
-		border-left: 2px solid var(--gray-200);
+		box-shadow: none;
 		margin-left: 10px;
-		border-radius: 0;
 		padding: 0 0 0 1.5rem;
 	}
 
@@ -140,6 +151,11 @@ h2 {
 	}
 }
 
+.toggleable-enabled :deep(.p-panel-content) {
+	border-left: 2px solid var(--gray-200);
+	border-radius: 0;
+}
+
 .content-wrapper {
 	display: flex;
 	flex-direction: column;
diff --git a/packages/web-forms/src/components/QuestionList.vue b/packages/web-forms/src/components/QuestionList.vue
index e2a8a78a0..eb17ca680 100644
--- a/packages/web-forms/src/components/QuestionList.vue
+++ b/packages/web-forms/src/components/QuestionList.vue
@@ -48,7 +48,7 @@ const isControlNode = (node: NonStructuralNode): node is ControlNode => {
 	<template v-for="node in nodes" :key="node.nodeId">
 		<template v-if="node.currentState.relevant">
 			<!-- Render group nodes -->
-			<FormGroup v-if="isGroupNode(node)" :node="node" />
+			<FormGroup v-if="isGroupNode(node)" :node="node" toggleable />
 
 			<!-- Render repeat nodes -->
 			<RepeatRange v-else-if="isRepeatRangeNode(node)" :node="node" />

From 8e2d5404d4fe7e6d1b09af25acf5dac290bf52f8 Mon Sep 17 00:00:00 2001
From: spwoodcock <sam.woodcock@protonmail.com>
Date: Mon, 10 Mar 2025 09:56:41 +0000
Subject: [PATCH 2/4] feat(QuestionStepper): add stepper component enabled by
 OdkWebForm stepperLayout prop

---
 .../web-forms/src/components/OdkWebForm.vue   |  19 ++-
 .../src/components/QuestionStepper.vue        | 155 ++++++++++++++++++
 2 files changed, 171 insertions(+), 3 deletions(-)
 create mode 100644 packages/web-forms/src/components/QuestionStepper.vue

diff --git a/packages/web-forms/src/components/OdkWebForm.vue b/packages/web-forms/src/components/OdkWebForm.vue
index e06d01d2a..2777d03c8 100644
--- a/packages/web-forms/src/components/OdkWebForm.vue
+++ b/packages/web-forms/src/components/OdkWebForm.vue
@@ -14,12 +14,21 @@ import { FormInitializationError } from '../lib/error/FormInitializationError.ts
 import FormLoadFailureDialog from './Form/FormLoadFailureDialog.vue';
 import FormHeader from './FormHeader.vue';
 import QuestionList from './QuestionList.vue';
+import QuestionStepper from './QuestionStepper.vue';
 
 const webFormsVersion = __WEB_FORMS_VERSION__;
 
 interface OdkWebFormsProps {
 	formXml: string;
 	fetchFormAttachment: FetchFormAttachment;
+
+	/**
+	 * Note: by default all questions will be displayed in a single list,
+	 * with collapsable groups. This param changes to a stepper layout
+	 * closer to Collect.
+	 */
+	stepperLayout?: boolean;
+
 	missingResourceBehavior?: MissingResourceBehavior;
 
 	/**
@@ -29,7 +38,9 @@ interface OdkWebFormsProps {
 	submissionMaxSize?: number;
 }
 
-const props = defineProps<OdkWebFormsProps>();
+const props = withDefaults(defineProps<OdkWebFormsProps>(), {
+	stepperLayout: false,
+});
 
 // eslint-disable-next-line @typescript-eslint/consistent-type-definitions -- evidently a type must be used for this to be assigned to a name (which we use!); as an interface, it won't satisfy the `Record` constraint of `defineEmits`.
 type OdkWebFormEmits = {
@@ -105,6 +116,7 @@ const emit = defineEmits<OdkWebFormEmits>();
 
 const odkForm = ref<RootNode>();
 const submitPressed = ref(false);
+const showSendButton = ref(props.stepperLayout ? false : true);
 const initializeFormError = ref<FormInitializationError | null>();
 
 initializeForm(props.formXml, {
@@ -197,13 +209,14 @@ watchEffect(() => {
 				<template #content>
 					<div class="form-questions">
 						<div class="flex flex-column gap-2">
-							<QuestionList :nodes="odkForm.currentState.children" />
+							<QuestionList v-if="!stepperLayout" :nodes="odkForm.currentState.children" />
+							<QuestionStepper v-if="stepperLayout" :nodes="odkForm.currentState.children" @endOfForm="showSendButton=true" />
 						</div>
 					</div>
 				</template>
 			</Card>
 
-			<div class="footer flex justify-content-end flex-wrap gap-3">
+			<div v-if="showSendButton" class="footer flex justify-content-end flex-wrap gap-3">
 				<!-- maybe current state is in odkForm.state.something -->
 				<Button label="Send" rounded @click="handleSubmit()" />
 			</div>
diff --git a/packages/web-forms/src/components/QuestionStepper.vue b/packages/web-forms/src/components/QuestionStepper.vue
new file mode 100644
index 000000000..03a0bab55
--- /dev/null
+++ b/packages/web-forms/src/components/QuestionStepper.vue
@@ -0,0 +1,155 @@
+<script setup lang="ts">
+import { ref, computed, watch, provide } from 'vue';
+import type { ComponentPublicInstance } from 'vue';
+import type {
+	AnyControlNode,
+	AnyUnsupportedControlNode,
+	GeneralChildNode,
+	GroupNode,
+	RepeatRangeNode,
+} from '@getodk/xforms-engine';
+import FormGroup from './FormGroup.vue';
+import FormQuestion from './FormQuestion.vue';
+import RepeatRange from './RepeatRange.vue';
+import ExpectModelNode from './dev-only/ExpectModelNode.vue';
+import Steps from 'primevue/steps';
+import ProgressBar from 'primevue/progressbar';
+import Button from 'primevue/button';
+
+const props = defineProps<{ nodes: readonly GeneralChildNode[] }>();
+const emit = defineEmits(['endOfForm']);
+
+const isGroupNode = (node: GeneralChildNode): node is GroupNode => {
+	return node.nodeType === 'group';
+};
+
+type NonGroupNode = Exclude<GeneralChildNode, GroupNode>;
+
+const isRepeatRangeNode = (node: NonGroupNode): node is RepeatRangeNode => {
+	return (
+		node.nodeType === 'repeat-range:controlled' || node.nodeType === 'repeat-range:uncontrolled'
+	);
+};
+
+type NonStructuralNode = Exclude<NonGroupNode, RepeatRangeNode>;
+
+type ControlNode = AnyControlNode | AnyUnsupportedControlNode;
+
+const isControlNode = (node: NonStructuralNode): node is ControlNode => {
+	const { nodeType } = node;
+
+	return (
+		nodeType === 'input' ||
+		nodeType === 'note' ||
+		nodeType === 'select' ||
+		nodeType === 'trigger' ||
+		nodeType === 'range' ||
+		nodeType === 'rank' ||
+		nodeType === 'upload'
+	);
+};
+
+// Compute step items (only groups, repeat ranges, and control nodes should be steps)
+const relevantNodes = computed(() =>
+	props.nodes.filter(node => node.currentState.relevant)
+);
+const steps = computed(() =>
+	relevantNodes.value
+		.filter(node => isGroupNode(node) || isRepeatRangeNode(node) || isControlNode(node))
+);
+
+// Handle stepper state
+const currentStep = ref(0);
+const isCurrentStepValidated = ref(true);
+const submitPressed = ref(false);
+provide('submitPressed', submitPressed);
+
+const validateStep = () => {
+    // Manually trigger submitPressed to display error messages
+	submitPressed.value = true;
+
+    const currentNode = steps.value[currentStep.value];
+    if (isGroupNode(currentNode) && currentNode.validationState.violations.length > 0) {
+        isCurrentStepValidated.value = false;
+    } else if (currentNode.validationState.violation) {
+        isCurrentStepValidated.value = false;
+    } else {
+        isCurrentStepValidated.value = true;
+    }
+}
+const nextStep = () => {
+    validateStep();
+
+	if (isCurrentStepValidated.value && currentStep.value < steps.value.length - 1) {
+        // Reset validation triggered later in the form
+	    submitPressed.value = false;
+        // Also reset validation state of current node
+        isCurrentStepValidated.value = true;
+		currentStep.value++;
+	}
+};
+const prevStep = () => {
+	if (currentStep.value > 0) {
+		currentStep.value--;
+	}
+};
+const isLastStep = computed(() => currentStep.value === steps.value.length - 1);
+watch(isLastStep, (newValue) => {
+    emit('endOfForm', newValue);
+});
+
+// // Calculate stepper progress
+// const totalNodes = computed(() => 
+// 	Math.max(relevantNodes.value.length - 1, 1) // Ensure at least 1 to avoid division by zero
+// );
+// 
+// const currentNodeIndex = computed(() => {
+//    const activeNode = steps.value[currentStep.value];
+//    if (!activeNode) return 0;
+//
+//    // Find the current node's position among relevant nodes
+//    const index = relevantNodes.value.findIndex(node => node.nodeId === activeNode.nodeId);
+//    return Math.max(index, 0); // Ensure it starts at 0
+// });
+//
+// const progress = computed(() => {
+// 	if (totalNodes.value === 1) return 100; // If there's only one relevant node, treat it as complete
+// 	return (currentNodeIndex.value / totalNodes.value) * 100;
+// });
+</script>
+
+<template>
+    <!-- TODO -->
+    <!-- <ProgressBar :value="progress"></ProgressBar> -->
+
+	<div class="stepper-container">
+		<div v-for="(step, index) in steps" :key="step.nodeId">
+			<template v-if="index === currentStep">
+				<!-- Render group nodes -->
+				<FormGroup v-if="isGroupNode(step)" :node="step" />
+
+				<!-- Render repeat nodes -->
+				<RepeatRange v-else-if="isRepeatRangeNode(step)" :node="step" />
+
+				<!-- Render individual questions -->
+				<FormQuestion v-else-if="isControlNode(step)" :question="step" />
+
+				<ExpectModelNode v-else :node="step" />
+			</template>
+		</div>
+
+		<div class="navigation-buttons">
+			<Button label="Previous" @click="prevStep" :disabled="currentStep === 0" />
+			<Button label="Next" @click="nextStep" :disabled="isCurrentStepValidated && currentStep === steps.length - 1" />
+		</div>
+	</div>
+</template>
+
+<style scoped lang="scss">
+.navigation-buttons {
+	display: flex;
+	justify-content: space-between;
+	width: 100%;
+	margin-top: 1rem;
+}
+</style>

From 0d0363cc2d21e24e7d37d2dd20b3a2134c344bd3 Mon Sep 17 00:00:00 2001
From: spwoodcock <sam.woodcock@protonmail.com>
Date: Mon, 10 Mar 2025 13:29:44 +0000
Subject: [PATCH 3/4] feat(QuestionStepper): update stepper layout to be closer
 to ODK Collect

---
 .../web-forms/src/components/OdkWebForm.vue   |  5 +-
 .../src/components/QuestionStepper.vue        | 91 +++++++++++++------
 2 files changed, 68 insertions(+), 28 deletions(-)

diff --git a/packages/web-forms/src/components/OdkWebForm.vue b/packages/web-forms/src/components/OdkWebForm.vue
index 2777d03c8..43cf4601a 100644
--- a/packages/web-forms/src/components/OdkWebForm.vue
+++ b/packages/web-forms/src/components/OdkWebForm.vue
@@ -210,7 +210,8 @@ watchEffect(() => {
 					<div class="form-questions">
 						<div class="flex flex-column gap-2">
 							<QuestionList v-if="!stepperLayout" :nodes="odkForm.currentState.children" />
-							<QuestionStepper v-if="stepperLayout" :nodes="odkForm.currentState.children" @endOfForm="showSendButton=true" />
+							<!-- Note that QuestionStepper has the 'Send' button integrated instead of using the button below -->
+							<QuestionStepper v-if="stepperLayout" :nodes="odkForm.currentState.children" @sendFormFromStepper="handleSubmit()" />
 						</div>
 					</div>
 				</template>
@@ -222,7 +223,7 @@ watchEffect(() => {
 			</div>
 		</div>
 
-		<div class="powered-by-wrapper">
+		<div v-if="showSendButton" class="powered-by-wrapper">
 			<a class="anchor" href="https://getodk.org" target="_blank">
 				<span class="caption">Powered by</span>
 				<img
diff --git a/packages/web-forms/src/components/QuestionStepper.vue b/packages/web-forms/src/components/QuestionStepper.vue
index 03a0bab55..061f7ddbb 100644
--- a/packages/web-forms/src/components/QuestionStepper.vue
+++ b/packages/web-forms/src/components/QuestionStepper.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { ref, computed, watch, provide } from 'vue';
+import { ref, computed, provide } from 'vue';
 import type { ComponentPublicInstance } from 'vue';
 import type {
 	AnyControlNode,
@@ -17,7 +17,7 @@ import ProgressBar from 'primevue/progressbar';
 import Button from 'primevue/button';
 
 const props = defineProps<{ nodes: readonly GeneralChildNode[] }>();
-const emit = defineEmits(['endOfForm']);
+const emit = defineEmits(['sendFormFromStepper']);
 
 const isGroupNode = (node: GeneralChildNode): node is GroupNode => {
 	return node.nodeType === 'group';
@@ -59,44 +59,47 @@ const steps = computed(() =>
 );
 
 // Handle stepper state
-const currentStep = ref(0);
-const isCurrentStepValidated = ref(true);
+const firstStep = 0;
+const finalStep = steps.value.length;
+const currentStep = ref(firstStep);
 const submitPressed = ref(false);
 provide('submitPressed', submitPressed);
 
-const validateStep = () => {
+const allFieldsValid = () => {
     // Manually trigger submitPressed to display error messages
 	submitPressed.value = true;
 
     const currentNode = steps.value[currentStep.value];
+
+    // Check group error array
     if (isGroupNode(currentNode) && currentNode.validationState.violations.length > 0) {
-        isCurrentStepValidated.value = false;
+        return false;
+
+    // Check question single error
     } else if (currentNode.validationState.violation) {
-        isCurrentStepValidated.value = false;
-    } else {
-        isCurrentStepValidated.value = true;
+        return false;
     }
+
+    return true;
 }
 const nextStep = () => {
-    validateStep();
+    if (!allFieldsValid()) {
+        // There was an error validating
+        return false;
+    }
 
-	if (isCurrentStepValidated.value && currentStep.value < steps.value.length - 1) {
+    // Do not increment further if at end of form
+	if (currentStep.value < steps.value.length - 1) {
         // Reset validation triggered later in the form
 	    submitPressed.value = false;
-        // Also reset validation state of current node
-        isCurrentStepValidated.value = true;
 		currentStep.value++;
 	}
 };
 const prevStep = () => {
-	if (currentStep.value > 0) {
+	if (currentStep.value > firstStep) {
 		currentStep.value--;
 	}
 };
-const isLastStep = computed(() => currentStep.value === steps.value.length - 1);
-watch(isLastStep, (newValue) => {
-    emit('endOfForm', newValue);
-});
 
 // // Calculate stepper progress
 // const totalNodes = computed(() => 
@@ -137,19 +140,55 @@ watch(isLastStep, (newValue) => {
 				<ExpectModelNode v-else :node="step" />
 			</template>
 		</div>
-
-		<div class="navigation-buttons">
-			<Button label="Previous" @click="prevStep" :disabled="currentStep === 0" />
-			<Button label="Next" @click="nextStep" :disabled="isCurrentStepValidated && currentStep === steps.length - 1" />
-		</div>
 	</div>
+
+    <div class="navigation-button-group">
+        <!-- If swapping to arrows: 🡨 🡪 -->
+        <Button v-if="currentStep > firstStep" class="navigation-button" label="Back" @click="prevStep" rounded outlined />
+        <Button v-if="currentStep === finalStep" class="navigation-button" label="Send" @click="allFieldsValid ? emit('sendFormFromStepper') : null" rounded />
+        <!-- Note the button ordering is important here as we use a last-child selector for styling -->
+        <Button v-if="currentStep < finalStep" class="navigation-button" label="Next" @click="nextStep" rounded outlined />
+    </div>
 </template>
 
 <style scoped lang="scss">
-.navigation-buttons {
+.stepper-container {
 	display: flex;
-	justify-content: space-between;
+	flex-direction: column;
+	flex-grow: 1;
+	overflow-y: auto;
+	padding-bottom: 3rem;
+
+	:deep(.p-panel) {
+		box-shadow: none;
+	}
+}
+
+.navigation-button-group {
+	display: flex;
+	position: fixed;
+	bottom: 0;
+	left: 0;
 	width: 100%;
-	margin-top: 1rem;
+	background: white;
+	padding: 1rem;
+	justify-content: space-between;
+	box-shadow: 0 -2px 5px rgba(0, 0, 0, 0.1);
+}
+
+/* Ensure Next button is on the right when Back is hidden */
+.navigation-button-group .navigation-button:last-child {
+	margin-left: auto;
+}
+
+/* If only one button is visible, align it to the right */
+.navigation-button-group:has(.navigation-button:first-child:last-child) {
+	justify-content: flex-end;
+}
+
+.navigation-button {
+    padding-left: 3rem;
+    padding-right: 3rem;
+    font-size: 1rem;
 }
 </style>

From 4f588f08d9c1bfa9c08019f15a7eabf6834ba42b Mon Sep 17 00:00:00 2001
From: DanielJDufour <daniel.j.dufour@gmail.com>
Date: Mon, 24 Mar 2025 07:50:24 -0400
Subject: [PATCH 4/4] bug fix: recompute final step when number of steps change

---
 packages/web-forms/src/components/QuestionStepper.vue | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/web-forms/src/components/QuestionStepper.vue b/packages/web-forms/src/components/QuestionStepper.vue
index 061f7ddbb..dc152b387 100644
--- a/packages/web-forms/src/components/QuestionStepper.vue
+++ b/packages/web-forms/src/components/QuestionStepper.vue
@@ -60,7 +60,7 @@ const steps = computed(() =>
 
 // Handle stepper state
 const firstStep = 0;
-const finalStep = steps.value.length;
+const finalStep = computed(() => steps.value.length - 1);
 const currentStep = ref(firstStep);
 const submitPressed = ref(false);
 provide('submitPressed', submitPressed);