[migration/ilib-js-to-dart] feat(date): add julianday/rd options to ILibDateOptions and fix DateFmt calendar/timezone conversion

[gouniLee]

Checklist

The following lists affects Pub Points on pub.dev when the package is published.

• Passed the all tests.
• Verified that the example app works.
• Executed the dart format command.
• Added the API description is added if necessary.

Summary

Adds julianday / rd inputs to ILibDateOptions (parity with JS DateFactory) and fixes several calendar/timezone conversion bugs in ILibDateFmt.format() that were uncovered by a follow-up code review.

What changed

Feature

• ILibDateOptions: new julianday and rd fields; _toCalendarDate() now cleanly separates the absolute-instant path (julianday/rd/unixtime/dateTime) from the component path.
• toCalendarDate(): new public method exposing the resolved ILibCalendarDate (matches what JS DateFactory returns directly).
• Locale-driven calendar: getCalendar() / _toCalendarDate() derive the calendar from locale when type/calendar is omitted, then fall back to gregorian.

Fixes

• Absolute instant + type: DateFactory({unixtime, type:'islamic'})-style input no longer misreads the decomposed Gregorian components as being in the caller's calendar (was producing wildly wrong dates like October 19, 2585).
• Timezone mismatch: format() now re-creates the date in the formatter's timezone when the input's timezone differs, gated on the date's timezone (matching JS (date.timezone || 'local') === formatterTz) rather than a formatter-explicit flag.
• Local DateTime: a non-UTC DateTime (isUtc=false) is no longer double-offset during calendar conversion.
• Caller components ignored for absolute instants: components are taken from the decomposed instant only, keeping them consistent with the hardcoded gregorian calendar.

Verification against iLib JS

All conversion results were checked 1:1 against iLib JS (DateFactory / DateFmt):

• unixtime + type:islamic → gregorian formatter → July 4, 2024 ✓
• unixtime → explicit islamic formatter → Ḏu al-Ḥijja 27, 1445 (= JS 1445-12-27) ✓
• GregorianDate(tz:'Europe/Berlin') → en-US formatter → 6:00 AM (Berlin→NY) ✓

Notes

Two review findings were investigated and intentionally not changed, as current behavior already matches iLib JS:

• ILibCalendarDate timezone comparison is unconditional (no formatter-explicit gate) — matches JS.
• The B (flexible day-period) selection with midnight-wrapping periods matches JS output.

Motivation

Enables the JS two-step pattern in Dart:

// JS equivalent:
// var g = DateFactory({type:'gregorian', year, month, day, timezone:'local'});
// var d = DateFactory({julianday: g.getJulianDay(), locale: iLibLocale, timezone:'local'});

final ILibCalendarDate localDate = ILibDateOptions(
  julianday: ILibDateOptions(
    type: 'gregorian',
    year: gregorianYear, month: month, day: day,
    timezone: 'local',
  ).getJulianDay(),
  locale: iLibLocale,
  timezone: 'local',
).toCalendarDate();

Test plan

• flutter test test/date/datefmt_datetime_calendar_extra_test.dart
• flutter test test/date/datefmt_TimezoneCalendar_extra_test.dart
• flutter test
• Example app integration test (fa-IR / am-ET datetime formatting)

[seonmiJin]

I've added test/date/datefmt_TimezoneCalendar_extra_test.dart.
Also, I've added these tests to the branch so they can be validated in JS iLib as well.
iLib-js/iLib@development...test-from-flutter-ilib

[gouniLee]

I've added test/date/datefmt_TimezoneCalendar_extra_test.dart. Also, I've added these tests to the branch so they can be validated in JS iLib as well. iLib-js/iLib@development...test-from-flutter-ilib

I’ve made updates so that everything works, including the test files you added, and I also updated the code after validating more diverse edge cases. Please check them again.