feat: custom calendar support

[ToyWalrus]

Closes #3270

Custom calendar support

This PR...

• Exposes the createCalendar prop on Calendar and RangeCalendar to allow for a custom calendar implementation
• Updates the Calendar interface with additional optional methods to implement:
  • getWeeksInMonth()
    • For overriding the getWeeksInMonth() method in @internationalized/date/src/queries.ts (Used when determining how many rows to display in a calendar for a given month)
  • getCurrentMonth()
    • For overriding the startOfMonth() and endOfMonth() methods in @internationalized/date/src/queries.ts
    • For updating the month's display name in a calendar
    • For modifying the styling of a range selection by defining different start and end dates for a range
    • For updating date math in @internationalized/date/src/manipulation.ts
      • When adding months to a date, instead of incrementing the month index by X, instead get the number of days in the current month and add that many days, then balance the date
      • When subtracting months from a date, instead of decrementing the month index by X, instead get the number of days from the previous month and subtract that many days, then balance the date
  • isSamePeriod()
    • For overriding isSameDay(), isSameMonth(), and isSameYear() in @internationalized/date/src/queries.ts (Used when determining whether to disable certain days because they're outside the current month. Added support for "day", "week", "month", and "year" for completeness)
• Adds two new stories
  • "Custom calendar" in @react-spectrum/calendar/stories/Calendar.stories.tsx that uses a custom 4-5-4 calendar implementation
  • "Custom calendar" in @react-spectrum/calendar/stories/RangeCalendar.stories.tsx that uses the same 4-5-4 calendar implementation
• Updates documentation for Calendar and RangeCalendar explaining how to create and use a custom calendar implementation

This change is backwards compatible and will not break any existing calendars.

✅ Pull Request Checklist:

• Included link to corresponding React Spectrum GitHub Issue.
• Added/updated unit tests and storybook for this change (for new code or code which already has tests).
• Filled out test instructions.
• Updated documentation (if it already exists for this component).
• Looked at the Accessibility Practices for this feature - Aria Practices

📝 Test Instructions:

I added a custom 4-5-4 calendar implementation that gets used in the added stories and test cases, at @internationalized/date/tests/customCalendarImpl.js. (Side note: I don't know if there's a better place for this file to live, since I didn't see any sort of "test utils" files that were commonly shared) This calendar was originally added to the Typescript calendar stories file in this PR's commit history but was later moved to a JS file in the test folder to be shared from there.

This custom calendar's correctness can be verified by using this link to a custom 4-5-4 calendar, or by comparing it to other such calendars found online.

🧢 Your Project:

Adobe, Analysis Workspace