Add `stepper-layout` prop to OdkWebForm component for Collect-like experience #329

spwoodcock · 2025-03-10T13:55:16Z

I have verified this PR works in these browsers (latest versions):

What else has been done to verify that this works as intended?

Tested the original 'list' view layout works too.

Why is this the best possible solution? Were any other approaches considered?

I tried my best to not add new superfluous code.
It's mostly either:
- Using built-in PrimeVue components.
- Using existing functionality built into web-forms already (such as the validation code).

How does this change affect users? Describe intentional changes to behavior and behavior that could have accidentally been affected by code changes. In other words, what are the regression risks?

No change for the default view - the stepper has to be enabled by a prop.

Do we need any specific form for testing your changes? If so, please attach one.

I was testing with this one:
mdp_fmtm_xlsform.xlsx

What's changed

Included

I added a new component QuestionStepper that mirrors the QuestionList component.
It's enabled by simply passing the stepper-layout prop to OdkWebForm.
Instead of displaying questions and groups via collapsible panels, instead a PrimeVue Stepper component is introduced, displaying one question or group of questions per page.
I kind of abused the submitPressed dependency to trigger the existing validation logic, without needing to add extra code - it seems to work nicely.
Video is in desktop view for easier recording, but mobile view is the preferred way to use the stepper:

Recording.2025-03-10.134548.mp4

Things I didn't do

I updated the FormPanel to have an optional toggleable prop. This allows us to disable the panel collapsing behaviour for the stepper. I didn't update RepeatInstance and RepeatRange to have a toggleable prop passed through to FormPanel too, but assume this may be needed?
I attempted to add a PrimeVue ProgressBar to the stepper. It works well in the layout, however, it's pretty tricky to assess the percentage complete for the form. This needs to be done via the available nodes, but based on relevant fields, additional nodes can be added causing the percentage complete to drop. I need to look into this in more detail - it's probably doable - if this is a desired feature.
I had to hide the 'Powered by ODK' button when using the stepper, as it has absolute positioning below the question panel. This could be fixed somehow if needed.

Note on the FormPanel border

I removed this entirely for the stepper based view, as it's not necessary imo:
Stepper view:

List view:
I kept the left border on collapsible FormPanel as it nicely demarcates where each group starts and ends.
- I assume that was why it is present? Else, easily removable via box-shadow CSS.

Extra notes

Styling is a mix of https://www.figma.com/design/KFi9hIQdrRgo0rLqIC7Sg8/ODK-Collect?node-id=5504-114737 and trying to keep in line with Collect - let me know your thoughts! @lognaturel @DanielJDufour
The send button displays in center screen on Collect, but here I added it in place of the next button on the stepper instead.
- This could be changed, but it complicates things a bit.

changeset-bot · 2025-03-10T13:55:19Z

⚠️ No Changeset found

Latest commit: 0d0363c

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

…gurable

…epperLayout prop

spwoodcock · 2025-03-10T14:06:49Z

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 />


I set the default for the prop toggleable to false, meaning the prop needs to be passed here to allow for the collapsable panels in the list view

spwoodcock · 2025-03-10T14:08:53Z

packages/web-forms/src/components/FormPanel.vue

@@ -140,6 +151,11 @@ h2 {
 	}
 }

+.toggleable-enabled :deep(.p-panel-content) {


Here I only add the style for the line on the left of the group if the panel is set to toggleable

spwoodcock · 2025-03-10T14:09:53Z

packages/web-forms/src/components/FormPanel.vue

 <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">


Adding the toggleable-enabled class dynamically

lognaturel · 2025-03-10T16:14:36Z

Thanks so much for exploring this and sharing what you've come up with! The video looks so good and it's great to see that the implementation is largely contained.

I'm going to change this to a draft for now to help with our review processes. We'd want to make sure there are tests and a design pass before considering for merge.

I think it makes sense for us to prioritize image capture and selects with images over reviewing and finalizing this, does that sound right?

spwoodcock · 2025-03-10T17:29:16Z

Thanks so much for exploring this and sharing what you've come up with! The video looks so good and it's great to see that the implementation is largely contained.

I'm going to change this to a draft for now to help with our review processes. We'd want to make sure there are tests and a design pass before considering for merge.

I think it makes sense for us to prioritize image capture and selects with images over reviewing and finalizing this, does that sound right?

Yep sounds good to me! We can finalise and discuss this further in the long term - I'll add tests too 😁

We can use this layout on our fork for the time being 👍

alyblenkin · 2025-03-10T17:42:23Z

@spwoodcock this is awesome! I'm working on designing the flows for image capture and selects with images. I'll share it with you once I have something ready to get your feedback.

spwoodcock added 3 commits March 10, 2025 13:57

feat(FormGroup): make underlying FormPanel toggleable prop user confi…

608ab4d

…gurable

feat(QuestionStepper): add stepper component enabled by OdkWebForm st…

8e2d540

…epperLayout prop

feat(QuestionStepper): update stepper layout to be closer to ODK Collect

0d0363c

spwoodcock force-pushed the feat/submission-stepper branch from 3579ece to 0d0363c Compare March 10, 2025 13:58

spwoodcock commented Mar 10, 2025

View reviewed changes

lognaturel marked this pull request as draft March 10, 2025 16:14

spwoodcock mentioned this pull request Mar 24, 2025

fmtm stepper fix hotosm/web-forms#3

Open

5 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add `stepper-layout` prop to OdkWebForm component for Collect-like experience #329

Add `stepper-layout` prop to OdkWebForm component for Collect-like experience #329

spwoodcock commented Mar 10, 2025 •

edited

Loading

changeset-bot bot commented Mar 10, 2025 •

edited

Loading

spwoodcock Mar 10, 2025

spwoodcock Mar 10, 2025

spwoodcock Mar 10, 2025

lognaturel commented Mar 10, 2025

spwoodcock commented Mar 10, 2025

alyblenkin commented Mar 10, 2025

Add stepper-layout prop to OdkWebForm component for Collect-like experience #329

Are you sure you want to change the base?

Add stepper-layout prop to OdkWebForm component for Collect-like experience #329

Conversation

spwoodcock commented Mar 10, 2025 • edited Loading

I have verified this PR works in these browsers (latest versions):

What else has been done to verify that this works as intended?

Why is this the best possible solution? Were any other approaches considered?

How does this change affect users? Describe intentional changes to behavior and behavior that could have accidentally been affected by code changes. In other words, what are the regression risks?

Do we need any specific form for testing your changes? If so, please attach one.

What's changed

Included

Things I didn't do

Note on the FormPanel border

Extra notes

changeset-bot bot commented Mar 10, 2025 • edited Loading

⚠️ No Changeset found

spwoodcock Mar 10, 2025

Choose a reason for hiding this comment

spwoodcock Mar 10, 2025

Choose a reason for hiding this comment

spwoodcock Mar 10, 2025

Choose a reason for hiding this comment

lognaturel commented Mar 10, 2025

spwoodcock commented Mar 10, 2025

alyblenkin commented Mar 10, 2025

Add `stepper-layout` prop to OdkWebForm component for Collect-like experience #329

Add `stepper-layout` prop to OdkWebForm component for Collect-like experience #329

spwoodcock commented Mar 10, 2025 •

edited

Loading

changeset-bot bot commented Mar 10, 2025 •

edited

Loading