Add default date question type

[latin-panda]

Implement the default date widget with the Gregorian calendar.

Support for appearances and additional calendar types—such as Bikram Sambat, Buddhist, Coptic, Ethiopian, Islamic, Myanmar, and Persian—is considered a future enhancement and will not be included at this stage

User stories

As a user, I want to navigate past or future dates and select a date.

Component state

• Read-only state
• Disabled state
• Display of errors

Libraries

Use the Primevue's date picker component and figma for states not in the library. The calendar's footer has an option with some navigation buttons, but we need to check if it's possible to translate those buttons.

Design

Figma

[latin-panda]

Test plan

• Date picker is required and the value is null

  • Prevent saving the form and highlight the question as required.

• Date picker is disabled

  • Shows the question label and the readonly info for the date. It cannot change the value

• Date picker has a relevant criteria

  • Shows question label and input when it becomes relevant.
  • Doesn't show anything when the question is not relevant.

• Date picker note variant

  • Shows the question label and the readonly info for the date

• Date picker value is correct

  • The value is formatted in the correctly [TBD format]
  • The value is null when the question isn't answered.

• Date picker UI display

  • Reacts to translation changes
    • Form built-in translations are working
    • Calendar's translation to be resolved in this ticket: Add translation support for UI components based on browser locale #332
  • Responsive design - should stack elements
  • It flows with other question types (similar styles: color, border, etc.)
  • Cross-browser: Chrome, Firefox, Safari, Chrome for Android, Chrome for iPhone
  • Stays within the viewport (no overflow) on small screens or when near edges
    • PrimeVue automatically tries to fit the calendar, but when it can't fit, then it's possible to scroll to see the rest of the calendar
  • Display calendar icon

• User wants to change a preselected date

  • Allows changing the question value by opening the calendar and selecting a new date
  • Allows canceling and keeping the previous value
    • Canceling here means: 1. user selects a date. 2. then opens the calendar again. 3. click somewhere else outside the calendar area. 4. calendar closes. 5. the previous value should stay (not cleared)

• User wants to navigate years and months in the past or future to select a date

  • Allows navigating across years and months

• User enters an incorrect date manually

  • Display error message when user types a date incorrectly: Feb 30 or 13/45/2023
    • It doesn't display an error message, but it doesn't allow setting an incorrect date - input remains empty

• User selects a date that doesn't pass the date picker constraint/validation

  • Display error message with constraint message
    • The input is configured to show the constraint message after the form's submit button is clicked

Sample forms for testing

date.xlsx

[alyblenkin]

I think the test plan looks great and covers everything in the doc! I only have two comments:

User wants to change a preselected date
Allows canceling and keeping the previous value

I don't think it's possible to cancel and keep the previous date with the component. If the user selects a date and then changes it, their options are to clear it or manually change it back.

My second comment is about the icon and I'm not sure if it needs to be in the test plan, but I think it would helpful to include the calendar icon is displayed next to the input field to help provide a visual cue.

[latin-panda]

@alyblenkin thanks for the feedback

My second comment is about the icon and I'm not sure if it needs to be in the test plan, but I think it would helpful to include the calendar icon is displayed next to the input field to help provide a visual cue.

I've added the calendar icon under Date picker UI display section

I don't think it's possible to cancel and keep the previous date with the component. If the user selects a date and then changes it, their options are to clear it or manually change it back.

Maybe this could be: '1. user selects a date. 2. then opens the calendar again. 3. click somewhere else outside the calendar area. 4. calendar closes. 5. the previous value should stay (not cleared)`

[alyblenkin]

Sounds good to me @latin-panda

[eyelidlessness]

Re: "needs design" label

I've re-added the "needs design" label here, as a prompt for hopeful design around:

• How we'll represent each of the following data types as values (engine/client interface):
  • date
  • time¹
  • dateTime¹
• Anticipated high-complexity state flow in UI component(s), if any

Re: value representation(s)

Something to think about in terms of the value representation(s): everything in @getodk/xpath dealing with the same (semantic) value types is implemented against the Temporal proposal. This was a deliberate choice, not just because the spec represents the future of date/time handling in JavaScript (TypeScript), but because there are important spec considerations around localization and time zones, which are incredibly challenging to get right when working with the native Date type.

I think it would be wise to consider adopting the same representation in the engine. As with support for geopoint, this would have the same opportunities and considerations for sharing encode/decode between @getodk/xpath and @getodk/xforms-engine. Since the PrimeVue component (or any other we'd likely use) will expect Date values, it's worth noting that there's also a pretty clear story for working between Temporal and Date values. This might be a bit of overhead (mental and runtime alike), but it very well may be worth it for the spec clarity it would afford!

As an added wrinkle to that, since Temporal is still a proposal, we're currently using a polyfill for it. There are a couple sub-issues to think about:

• The polyfill we're using is outdated. This is tracked in Prepare for standardization of Temporal #199.
• We also have a general need to address shared dependencies across package boundaries (internally in Web Forms, as well as at the Web Forms/host application boundary e.g. with Vue)

Note: It's also worth considering using Temporal representations internally in the engine, with each value types' ValueCodec handling any Temporal/Date shuffling that might be necessary or appropriate. This could be appealing for the UI client, but it may make testing more challenging.

Re: PrimeVue component

I think it's also important to call out: until we upgrade to PrimeVue 4, we should always be sure to reference their v3 docs! This is easy to forget. It's helped me to build a bit of muscle memory for it, by always selecting "v3" in the dropdown on their landing page, before I navigate anywhere else. I'm calling this out because @lognaturel and I had some confusion about whether PrimeVue 3 even has date/time components. It turns out that it does! But in v3 they're named Calendar.

Footnotes

1. I'm not clear on whether these are in scope! The issue text doesn't mention times, only dates. But the second Figma screenshot shows an interface for setting time values. ↩ ↩²

[latin-panda]

I'm not clear on whether these are in scope! The issue text doesn't mention times, only dates. But the second Figma screenshot shows an interface for setting time values.

@eyelidlessness @alyblenkin This ticket is only for the date question type (input type="date")

[latin-panda]

Translations will be handled in this ticket: #332
For the time being, users can use the built-in browser translation tool: