Make it easier to set date values

[frankieroberto]

This updates the dateInput component to make it easier to set the values (for example, if going back to a page), without having to set the individual items.

For example, currently if you do this:

{{ dateInput({
  id: "example",
  namePrefix: "example",
  fieldset: {
    legend: {
      text: "What is your date of birth?",
      classes: "nhsuk-label--l",
      isPageHeading: true
    }
  }
}) }}

There is no way to set the value for each of the day, month and year components. To do that, you need to specify the items manually, include their css classes and labels:

{{ dateInput({
  id: "example",
  namePrefix: "example",
  fieldset: {
    legend: {
      text: "What is your date of birth?",
      classes: "nhsuk-label--l",
      isPageHeading: true
    }
  },
  hint: {
    text: "For example, 15 3 1984"
  },
  items: [
    {
      name: "day",
      classes: "nhsuk-input--width-2",
      value: "1"
    },
    {
      name: "month",
      classes: "nhsuk-input--width-2",
      value: "12"
    },
    {
      name: "year",
      classes: "nhsuk-input--width-4",
      value: "2024"
    }
  ]
}) }}

This PR proposed a shorter option, by doing this:

{{ dateInput({
  id: "dob",
  namePrefix: "dob",
  fieldset: {
    legend: {
      text: "What is your date of birth?"
    }
  },
  values: {
    day: "5",
    month: "8",
    year: "2024"
  }
}) }}

Additionally, the name attribute has changed from namePrefix-day to namePrefix[day]. This is to aid in prototyping, as the NHS Prototype Kit uses the square brackets to save the data in a nested key within data. This means you can do this:

{{ dateInput({
  id: "dob",
  namePrefix: "dob",
  fieldset: {
    legend: {
      text: "What is your date of birth?"
    }
  },
  values: data.dob
}) }}

You can also use top-level values object with a custom items array as a shorthand, allowing you do this:

{{ dateInput({
  id: "example",
  namePrefix: "example",
  fieldset: {
    legend: {
      text: "What is your date of birth?",
      classes: "nhsuk-label--l",
      isPageHeading: true
    }
  },
  values: {
    month: "12",
    year: "2024"
  },
  items: [
    {
      name: "month",
      classes: "nhsuk-input--width-2"
    },
    {
      name: "year",
      classes: "nhsuk-input--width-4"
    }
  ]
}) }}

Setting value within the items still works as well.

[frankieroberto]

A similar change has been proposed for GOVUK frontend: alphagov/govuk-frontend#4932

[edwardhorsford]

To confirm - would this be a breaking change?

[frankieroberto]

To confirm - would this be a breaking change?

Yes, I think so? It doesn’t change the visual output at all, but does change the default name values when using the namePrefix with no items array specified.

Incidentally, all of the examples on Date input specify the full items array, even though most of them don’t need to as they're outputting the default Day, Month, Year options. 🤔

[anandamaryon1]

This looks good. Just to check, does this still allow for items, for flexibility? Eg. day of week, week of year etc.

To confirm - would this be a breaking change?

Yes, I think so? It doesn’t change the visual output at all, but does change the default name values when using the namePrefix with no items array specified.

Incidentally, all of the examples on Date input specify the full items array, even though most of them don’t need to as they're outputting the default Day, Month, Year options. 🤔

This means we'll also need a ticket to update the service manual examples separately?

[frankieroberto]

This looks good. Just to check, does this still allow for items, for flexibility? Eg. day of week, week of year etc.

Yes, it didn't affect that at all, although @edwardhorsford's suggestion might also make it easier to set values once even if you're using custom items.

This means we'll also need a ticket to update the service manual examples separately?

Yeah, probably? That could even be done now, as the first example on the page sets custom items even though they're the same as the default ones. Although perhaps there’s a good reason for this – consistency with the second examples where the error classes are added?

Actually there could be a separate task to also make it easier to set the error classes on the default items, similar to what Joe has suggested - but that could be a follow-up, and feels a bit lower priority, given Nunjucks is rarely used in production here, and most prototypes don’t bother with error handling?

[frankieroberto]

@anandamaryon1 have updated the README for this component.

This change would also need an update to the Nunjucks macro documentation in the NHS design system docs.

I’ve tagged this as a breaking change, so it might need a bit of explanation in the release notes for the version of nhsuk-frontend that it goes out with. Something like this maybe:

Date input component
The default name attribute for each of the 3 date part input has changed from using a
prefix with a hyphen (eg dob-day) to a prefix with square brackets around the date
part (eg dob[day]). This is to enable the date part values to be automatically nested
as an object within frameworks like the NHS Prototype Kit, allowing you to do {{ data.dob.day }} instead of {{ data["dob-day"] }}.
You can override the default name attributes by setting name values for each of
the date parts within the items array and not setting a namePrefix.