implementing a custom calendar

[kabaros]

I am trying to implement a custom calendar (nepali) based on the Temporal specs and js-temporal polyfill. So far, I could only do it by forking the library itself, is that the expected way? I am assuming I should implement the Calendar interface, and the problems I am having fall under two categories:

1. Calendars expect BuiltinCalendarId type and there is no way to extend it.
2. If I get around problem 1, then the NonIsoImpl and HelperBase are not exported from the library so I have to duplicate a lot of the code to have a good starting point. can these be exported? or is the expectation for custom calendars to implement every thing from scratch?
3. I am unclear about "slots" concept .. do I need to generate the slots for my custom calendar?

I am wary that I am potentially asking to expose implementation details that are not part of the specs, but I am wondering - in general - if you have any pointers or recommendations about how people should implement custom calendars?

[ptomato]

That's cool that you are working on a custom calendar that's not yet in ICU! Here are some general tips and recommendations on implementing custom calendars: https://tc39.es/proposal-temporal/docs/calendar.html#custom-calendars

I'll try to answer your questions more specifically:

So far, I could only do it by forking the library itself, is that the expected way?

That isn't really the expected way. The expected way would be that you extend Temporal.Calendar with something like class Nepali extends Temporal.Calendar { ... }, and either export that class, or a single instance of it.

If you are additionally writing a polyfill (for example, to add a calendar that newer browsers have support for and older browsers don't), then you'd also need to monkeypatch a lot of methods in order to be able to implement the string-to-calendar conversion, e.g. to be able to deserialize strings like 2022-10-18[u-ca=nepali]. But that's not recommended except for that specific use case. Normally, code that wants to use a custom calendar is responsible for getting an object instance and passing it to the correct APIs.

Calendars expect BuiltinCalendarId type and there is no way to extend it.

I assume you mean as the argument to the constructor? It's true that each calendar needs to have a builtin calendar ID passed in to the constructor. This ID determines how the methods behave when you chain up, e.g. with super.dateAdd(...). If you are implementing a calendar that is similar to or a variant of one of the builtin calendars, you can use that existing calendar as the builtin ID, and only reimplement the methods that need to change. If the calendar you are implementing is not similar to any builtin calendar, then just use "iso8601" and override all the methods without chaining up.

If I get around problem 1, then the NonIsoImpl and HelperBase are not exported from the library so I have to duplicate a lot of the code to have a good starting point. can these be exported? or is the expectation for custom calendars to implement every thing from scratch?

The expectation is to implement everything from scratch unless you can implement it by chaining up to a method from Temporal.Calendar.prototype. For example, dateAdd(date, duration, options) { return super.dateAdd(date, duration, options); } with or without some adjustments before or after the super call.

Exporting these helpers seems like it could be a good use case for a separate calendar helper library (if it were to exist), not for a polyfill though — that might confuse people as to what is part of the proposal and what isn't. NonIsoImpl and HelperBase certainly wouldn't be available in a browser that implements the proposal, so it would be bad if code that relied on those objects broke when switching from this polyfill to the native implementation.

Those objects are likely to be removed in the future anyway. We have a vague plan to use ICU4X for calendar calculations instead of this custom code, although no timeline for this change.

I am unclear about "slots" concept .. do I need to generate the slots for my custom calendar?

Slots are a concept that kind of only has meaning in the specification. You can think of them as private properties. You don't need to take them into account when implementing a custom calendar.

Good luck and I hope you'll share a link when you've got a first version!

[kabaros]

thanks a lot @ptomato for the thorough explanation. Extremely helpful!

I managed a first version here and seems to work as expected. I have some followup questions:

• I can convert from my nepali calendar to iso8601 but what methods do I need to implement to support the opposite (from iso8601 to nepali calendar)? I didn't see examples for the opposite for the other built-in calendars.

• I am using the Temporal api to build a calendar widget that can be localised by the client. I am using .toLocaleString to get hold of name of months, days, year in a certain locale. This works for built-in calendars, but I don't know how I can do the same for my custom calendar, to be able to do zdt.toLocaleString('ne-NP', { month: 'long'}) for example to get the name of a month in Nepali script. I could achieve this from the client using resource files and such, but is there a better way to do this?

• Is there anything else I am missing from this calendar implementation?

• Finally, a very generic question that's a bit out of topic: when it comes to lunar or lunisolar calendars, how should calendars handle these, as the end/start of a month is not known beforehand? From this comment, I understand that the implementation of calendars themselves are not part of Temporal, and they will be standardised as part of the Internationalisation API, but I am just curious about how that can be standardised in practice? (and the implication on building a UI component to display such a calendar, should the start and end of a month be flexible with +/- day for example)

[ptomato]

I can convert from my nepali calendar to iso8601 but what methods do I need to implement to support the opposite (from iso8601 to nepali calendar)?

The reverse conversion is done in the year(), month(), monthCode(), day() methods, as well as the auxiliary ones like daysInMonth() etc. (This is also the answer to "is there anything else I am missing" 😄)

About toLocaleString(), unfortunately it's not going to be possible to add a locale using the Nepali calendar to Intl.DateTimeFormat unless you polyfill the whole Intl object... I expect what you currently get from zdt.toLocaleString('ne-NP', { month: 'long'}) is a RangeError because the calendar associated with the ne-NP locale is gregory, which doesn't match nepali. So what I'd recommend doing is wrapping the month name function to check if the passed-in ZonedDateTime has the Nepali calendar and returning the month name from a table of month codes (indexed with zdt.monthCode) to localized names. (Do you need to localize the Nepali month names into any other languages as well? That's another use case to consider.)

About lunar/lunisolar calendars - the Internationalization API uses the calendar calculations in the CLDR (Common Locale Data Repository). Particularly for the Hijri calendar there are several different variations (see e.g. https://cldr.unicode.org/development/development-process/design-proposals/islamic-calendar-types) including arithmetically calculated ones like islamic-tbla and astronomically calculated ones like islamic-umalqura.

The islamic-rgsa one is the calendar based on sightings in Saudi Arabia in particular ("rgsa" stands for Regional - Saudi Arabia). I don't know for sure, but my guess is that the islamic-rgsa calendar estimates dates in the future, and when the actual sightings are made, the corrections are pulled in to browsers via a CLDR update. None of the CLDR calendars are parametrizable, so implementing +/- correction days (as I'm aware lots of software does) needs to be done with a custom calendar. (In fact, that's one of the stronger reasons we have custom calendars in Temporal.)

I'll cc @sffc here who might be able to add something to this.

[sffc]

I don't have a lot to add beyond @ptomato's great response, other than to emphasize that:

1. If you're dealing with custom calendars, you need to pass the calendar argument any time you create a new Temporal object (since we can't rely on the global built-in-calendar string registry)
2. Custom calendars give you full-purpose arithmetic APIs, but you likely need to implement custom localized formatting. Intl.DateTimeFormat only has symbols for built-in calendars. There is a ticket Data-Driven API tc39/ecma402#210 for APIs to extend Intl.DateTimeFormat with more data, but it's still pretty far out. In the mean time, to implement custom formatting, it wouldn't be completely wrong to format in a similar calendar and then use formatToParts to substitute in the correct symbols (like month names).

[kabaros]

just wanted to drop a note to say thanks again for the help here @ptomato and @sffc . The Nepali implementation is (almost) ready and you can see it here and this is a calendar component using it to display a Nepali calendar.