feat(#8681): support requiring countdown-timer fields

[SheilaAbby]

Description

This update ensures the countdown-timer widget applies to questions with the input type 'trigger' rather than 'note'.
In contrast to a note, a 'trigger' input can be configured with 'required' set to 'yes'. This setup ensures that if a user tries to bypass the timer before it completes, they will get a 'This field is required' constrain message.

NB: Just like the previous implementation on a note, workflow developers are allowed set custom timer durations, now on a new column labelled instance::cht:duration

Here is a sample xlsx that was used to test this feature
Uploading assessment_endemic.xlsx…

The updated countdown widget code will identify the trigger question types with the attached countdown timer and set the trigger question type OK radio button as checked when the timer completes running. The selected OK value can then be used to control subsequent questions linked to the countdown widget.

See screenshot,

#8681

Code review checklist

• Readable: Concise, well named, follows the style guide, documented if necessary.
• Tested: Unit and/or e2e where appropriate
• Internationalised: All user facing text
• Backwards compatible: Works with existing data and configuration or includes a migration. Any breaking changes documented in the release notes.

Compose URLs

If Build CI hasn't passed, these may 404:

• CHT_CORE_COMPOSE_URL
• COUCH_SINGLE_COMPOSE_URL
• COUCH_CLUSTER_COMPOSE_URL

License

The software is provided under AGPL-3.0. Contributions to this project are accepted under the same license.

[jkuester]

This is a great start! I have added a few small suggestions for simplifying things, but then I noted one design element that we missed here! Once we make a decision on question-types and parameter vs default we can circle back for another round of changes (and look at adding some tests).

[SheilaAbby]

This is a great start! I have added a few small suggestions for simplifying things, but then I noted one design element that we missed here! Once we make a decision on question-types and parameter vs default we can circle back for another round of changes (and look at adding some tests).

@jkuester Thanks a lot for the comments! working on the suggested changes.

[jkuester]

Okay! Now that we finally landed on how we want to proceed, we can make some real progress here! I have added a couple suggestions in-line for how we can update the widget to support the trigger questions. We will also need some changes to a few additional files:

medic.less:

We need to update this line in the css to properly hide the trigger bullet elements. I think we can just change this line to be:

    input, .option-wrapper {

Unit tests

Unfortunately, we do not have any existing unit tests for this widget, so we are going to have to add some. I think the best way to start would be to just try to follow the pattern in the phone-widget.spec.ts in a new countdown-widget.spec.ts file. It would be great if you give this a shot! I am afraid these tests will get a bit tricky, tough, since we probably do not want to actually wait for the timer for 60sec to complete. Hopefully we can stub around with sinon and rewire enough to get something useful. Please reach out, though if you get stuck!

I am going to work on adding the server-side code to the api that we need to actually load the cht:duration attribute from the form xml. When I get that done, we can merge it in here and it can all go into master together!

[jkuester]

@SheilaAbby I got the server-side changes done! I put them all in this PR pointed back at your branch. When you are ready, you can merge that PR (into your make-countdown-timer-required branch) and then those changes will be included in this PR. You can test the functionality by following the steps noted in the description for that PR.

[SheilaAbby]

@SheilaAbby I got the server-side changes done! I put them all in this PR pointed back at your branch. When you are ready, you can merge that PR (into your make-countdown-timer-required branch) and then those changes will be included in this PR. You can test the functionality by following the steps noted in the description for that PR.

That's good news! Thank you! Let me pull the changes

[jkuester]

Alright @SheilaAbby! I have added some unit/e2e tests and everything seems to be working just like we want! I have just a few more minor cleanup comments here and I will also reach out to get a few more Medic colleagues to review what we have done.

[jkuester]

@latin-panda @lorerod can you have a look at this PR when you get some time?

Summary:

The goal of this PR is to be able to require that a user run and wait for the timer, before continuing to the next page of the form. To support the require column for timers, we had a switch up how you can define a timer in the xlsx (while maintaining backwards compatibility with the old-style of notes). Previously, you created a timer by using a note question with the countdown-timer appearance. notes cannot be required, so we have switched to supporting the countdown-timer appearance on timer questions. Also, instead of providing the custom timer duration value in the default column, now you should set the value in a custom instance::cht:duration column.

Usage:

• In your xlsx form:
  • On the settings tab, add a namespaces column and set the value to cht=https://communityhealthtoolkit.org
  • On the survey tab, add a new question with:
    • type = trigger
    • appearance = countdown-timer
    • instance::cht:duration = 10
    • required = true()
• Build your branch with all the latest changes and run the CHT locally
• Use cht-conf to convert/upload your form
• Open the form via the webapp and see that you have a timer displayed. It should be required (cannot proceed without running the timer). And it should run for 10 seconds.

[latin-panda]

Great contribution! I left some comments inline and also below:

1. @jkuester, is there any PR documenting this work in cht-docs? Something to include for example is: Why adding cht=https://communityhealthtoolkit.org in the setting tab? What other values are supported?

2. You can also consider including a form with this @ support-scripts repo.

3. Testing:
   Node: 16, 18 & 20
   Phyton: 3.12
   Form: enketo_widgets.xlsx see row 14
   OS: Mac Sillicon
   Verion: Latest from branch SheilaAbby:make-countdown-timer-required
   Result: Not working for me

I get this error whenever I do the instructions here.

I tried changing the required value from true() to yes like in some other xlsx but still not working. If I remove the widget in row 14, then it builds fine.

[latin-panda]

Is it possible to put all the functions from here to the top (drawArc, drawCircle, etc.) inside the animate function, so it works better as a "class"?

[jkuester]

So, I spent way longer than I should have agonizing over the best way to structure this code and I am still not at all happy with how it is. In general I am not a fan of nesting functions in other functions to create a pseudo-class. I think it is terrible for readability and maintainability since everything in the function has access to so much state and the logic flow can jump all over the place. This case is extra tricky since so much of the logic is tied to the mutable state of running. From a readability perspective, I feel like a proper class here would be better than nested functions. However, JS classes are complete trash until ES2022 when they finally added support for private properties (while we are still targeting ES2018) and I could not find any other place in our entire code base where we actually used a JS class, so I was hesitant to introduce one here.

In the end I tried to split the difference and break out the functions that did not rely on the internal state of animate so they could be considered separately while only keeping the internal functions in animate that required access to the internal state of that function.... But like I said, I am still not really happy with how things turned out. Let me know your thoughts here! I am happy to just put all the functions back into animate if you think that would be best!

[jkuester]

@latin-panda thanks for the detailed feedback here! ❤️

1. Got the Docs PR logged! For the record, I did answer the namespaces question in the docs PR.
2. Good call on the support-scripts example! I have updated the existing countdown-timer form: https://github.com/medic/support-scripts/pull/13
3. Regarding the error you are getting when trying to convert the form, it looks like there are two issues with your form! First, your question name on row 14 is wait for timer when it should be something like wait_for_timer (with no whitespace). But also, on the settings tab, you named the column settings when it should actually be namespaces.

[lorerod]

Thank you, @jkuester, for all the unit tests and e2e tests you added. You are even maintaining the deprecated functionality tested.

[latin-panda]

It sparks ✨✨✨
Thanks!