Should there be a page in the docs with guidance for library authors?

[justingrant]

Along with our proposed flowchart (#655) of how to pick the right Temporal type, should we also have a page in the docs with guidance for library authors? Topics could include:

• What types should my library accept as input, and in what use cases?
• What types should my library emit as output, and in what use cases?
• Be careful of implicit assumptions, especially around time zones. For example, @ljharb brought up a case where Twitter's date picker broke as a result of Brazil's missing midnight after a DST transition. In a future where a date-picker library is built using Temporal, it might seem fine for it to accept and/or return a DateTime because no time zone is shown or accepted in the UI. But if the library's implementation is making assumptions that require a time zone, then using LocalDateTime might be more appropriate for the use case.
• Serialization and deserialization, including custom formats and interop with other systems. This includes parsing and formatting guidance, but also includes guidance for how to handle limitations and incompatibility between Temporal and other platforms. For example, if your library pulls an OffsetDateTime from a Java or .NET web service, how should that value be represented in Temporal?
• How to migrate the implementation of a library from moment, date-fns, legacy Date, etc. ? What changes and problems to expect?

There's some overlap with user-facing guidance, but I suspect that some of the issues that library authors run into (e.g. how to pick types properly to minimize their users running into errors like @ljharb noted) might be unique to libraries.

[Eonasdan]

Hello, I maintain a popular OSS date/time picker. I'm excited to see what Temporal is bringing to the JavaScript table because let's face it, the JS Date object kinda sucks.

I'm interested, as time permits, to create a POC that uses Temporal in place of my custom DateTime object (extends Date with some shortcuts and wraps Intl.DateTimeFormat).

As I mentioned over here. I'd love to see what temporal can do for my picker and I hope at some point Temporal includes some moment/dayjs style parsing, e.g. Temporal.from('2022-10-25', 'yyyy-MM-dd')

[ptomato]

Moved to the developer-education task list: js-temporal/temporal-developer-education#4