Get DatePicker, Calendar and DateInput to a known/agreed state in Labs, ready for core

[mark-tate]

DatePicker, Date Input and Calendar are in Labs, ready for promotion to Core, once we have some user-feedback from Stakeholders.

This PR should collate the known issues/discussions, so we make sure we move a stable feature set to Core.

• Confirm the tab order and focus pattern when confirmation pattern is used @ivan-calderon
• US date formatting requires a comma, confirm how US dates should be entered and formatted.
  @ivan-calderon
• A11y SME review, what is the gap to both WCAG 2.1 AA and also WCAG 2.2 AA ?
• Overlay discussion, is there some functionality we are missing in Core

[origami-z]

Adding Calendar children API discussion here. children is not the only way to make "composition".

When picking the use of children, need to think about whether it's intuitive in relationship to the physical space, e.g. children for a Card is very clear that things would be put "inside" of card. Obviously in certain use cases (like lexical means not exactly the same).

In Calendar's case, is it clear without looking at actual render, that it's about adding something to the top section of calendar? <Calendar> xyz </Calendar> (intentionally use xyz to make the case, use Navigation makes it mixing API discussion)

Some potential alternative

1. Make it clear it's something like header, e.g., <Calendar Header={'xyz'} />, which Header could be swapped to be something different than the default navigation component. This means calendar can still be composed with other options
2. Continue to use children, but make both navigation and month view to be children. e.g.

    <Calendar>
      <CalendarNavigation />
      <CalendarMonthView />
    </Calendar>

[mark-tate]

We will push this to Core, once we have had feedback from stakeholders.
Extending to end of Q3, we may release beforehand if we get the feedback we need

[ivan-calderon]

About date formatting @bhoppers2008 recently shared the following by email.
"- Date should always default to a locale in format where month is always text.

• Never leave the date as numeric.
• Allow input in a number of different formats that default to the month as text.
• (Consider partial entry of DD MM–defaulting to current year)."

[ivan-calderon]

@mark-tate. In relation to the "tab order and focus pattern when confirmation pattern is used". It is working as intended in the examples. TYVM!

[mark-tate]

Frappe Goal: update in Labs with design feedback and then find Stakeholder feedback

[jake-costa]

Emailed @mark-tate with the a11y review and will discuss findings on Thursday 9/26/24

[mark-tate]

Galao Goal: complete all of a11y feedback
@jake-costa to provide announcement spec

[origami-z]

I found it very hard to write custom parser / formatter using @internationalized/date, this could create more support / DX issue for us. Was talking to @mark-tate, we may need to consider introduce an adapter pattern, so users can plug in their own chosen date library.

[origami-z]

Not sure why startAdornment is not supported in DateInput but only endAdornment?

[origami-z]

Adding searching result date libraries in package.json

• moment - 4.1k
• date-fns - 229
• dayjs - 106
• luxon - 59
• internationalized/date - 12

[mark-tate]

Latte Goal: add adapter support for moment and internationalised for Calendar, DateInput and DatePicker
This will take the form of a LocalizationProvider which accepts an adapter and also manages locale and any other defaults, that Date controls need.

Work in progress on this branch
#4291
We have reworked selection of the date, so we can extract validation from the code.
You can never select an invalid date in the Calendar but you can in the Date Inputs, equally there is a transient state created by confirmation where you need to manage date updates. We are trialing this code within a form, that uses yup for validation to see if the latest approach improves on what we had.

[origami-z]

SO 93199 mentioned the need for isDayDisabled with both Calendar (via CalendarProps) and Date Input. We could have one example for it.

[mark-tate]

Latte Goal: adds tests for adapter support, push to Labs, seek stakeholder feedback

[ivan-calderon]

@mark-tate Disabled and Un-selectable calendar items' styling is not correct in our current site docs. I think you are aware of those required updates already. If not, please consider those fixes.

I put a temporary description of the correct characteristics in this example. Thank you!

[mark-tate]

Macc Goal: tests pass, site docs updated

[origami-z]

Mocha: Docs, fix issues from lab.52 version , MTK feedback

[mark-tate]

Mocca Goal: polish and address identified issues

Stretch goal: example, range picker with one calendar

[bhoppers2008]

New release made on Friday. User testing. Follow issues likely. @mark-tate can we close this specific issue now?

[origami-z]

User feedback - to open the calendar on click of input, however overlay focus management will not allow the input to be focused. Something to iterate on.

• SO 94724, SO 94545
• User feedback I687283

cc @jake-costa

[mark-tate]

By EOS,

• controlled open on focus (a11y concerns here, @jake-costa to help on this)
• adapter bundling - avoid bundling un-used libs
• blog published, dependent on adapter fix
• prioritise any other bugs which maybe raised during red eye

[jake-costa]

@mark-tate @origami-z

A11y response to user feedback (controlled open on focus):

1. Calendar cannot be opened when input or "open calendar" button receives focus.

2. Calendar can be opened on click of input but focus needs to remain on the text input.
   a. If the user presses tab after clicking the input, focus should move to the "open calendar" button and the displayed
   calendar should close.

3. Calendar can be opened on arrow down key press when input is focused but focus needs to move to the calendar.

4. Pressing esc should place focus back on the appropriate trigger element:
   a. Input if arrow down was pressed.
   b. Button if "open calendar" button was triggered.

5. The "open calendar" button should contain aria-haspopup=”true/false”.

6. When focus is in the Calendar it should trap focus.

7. Calendar should be labeled as "Datepicker" or "Choose a date" or something similar.

Let me know if you have any questions or want to discuss this.

[bhoppers2008]

Outstanding features to resolve in labs + feedback required:

• Open on click feature
• Date Adaptors split

[dplsek]

@mark-tate can update when he returns

[mark-tate]

A version of datepicker will be released w/e 20th Jan to support

• Open on click feature
• Date Adaptors split

A11y updates will start to appear in tecno sprint

[mark-tate]

tecno goal: a round of a11y improvements, no api change expected

[mark-tate]

PR released for adapters
PR review for behaviour by Fernanda and Josh

[jake-costa]

@mark-tate FYI I see on the PR it says openOnFocus prop was added however Calendar cannot be opened when input or "open calendar" button receives focus.

Also, Calendar can be opened on click of input but focus needs to remain on the text input. Currently the example has focus moving to calendar when the input is clicked.
And if the user presses tab after clicking the input, focus should move to the "open calendar" button and the displayed
calendar should close.

[mark-tate]

focus and sync between input and calendar being addressed by EOS

[mark-tate]

PR updated.. we just added

• openOnClick as an option and made open on down arrow by default
• input retains the focus now when using openOnClick

[mark-tate]

Oregano Goal:
quantify the a11y iteration

[mark-tate]

aim to merge behaviour changes in next release