feat: Introduce DateAdapter abstraction layer to support custom date libraries and calendars

[hamedaravane]

What problem does this feature solve?

Currently, ng-zorro-antd tightly couples its date handling logic with the date-fns library through the CandyDate class. This tight coupling limits the flexibility for developers who need to use alternative date libraries or support different calendar systems, such as the Jalali (Persian) calendar, which is widely used in Iran and other Persian-speaking countries.

In my application, I need to display and manipulate dates using the Jalali calendar. However, due to the current design, integrating Jalali date handling is not feasible without significant modifications to the ng-zorro-antd source code. This limitation hampers the ability to provide a localized and culturally appropriate user experience for end-users who rely on calendars other than the Gregorian calendar.

By introducing a DateAdapter abstraction layer, ng-zorro-antd can allow developers to plug in custom date implementations. This approach is similar to what Angular Material offers and aligns with Angular's flexible and modular design principles. It enables support for various calendar systems and date libraries (e.g., Moment.js, jalali-moment, date-fns-jalali), enhancing the internationalization capabilities of ng-zorro-antd.

Implementing a DateAdapter would solve the problem by decoupling the date handling logic from a specific library, allowing developers to:

• Use their preferred date library.
• Support different calendar systems required by their application's audience.
• Improve the end-user experience by displaying dates in the users' local calendar system.

This feature would make ng-zorro-antd more versatile and applicable to a broader range of applications with diverse internationalization requirements.

What does the proposed API look like?

• Introduce a DateAdapter Interface: Define an abstract class or interface specifying all necessary date operations required by ng-zorro-antd components (e.g., addDays, isSameDay, parse).

• Implement a Default Adapter Using date-fns: Provide a default implementation of DateAdapter using date-fns, ensuring existing functionality remains unaffected.

• Modify CandyDate to Use DateAdapter: Update the CandyDate class to utilize the DateAdapter for all date operations, decoupling it from date-fns.

• Allow Custom DateAdapter Implementations: Enable developers to provide custom DateAdapter implementations via Angular's dependency injection, allowing the use of alternative date libraries and calendars (e.g., jalali-moment for the Jalali calendar).

• Maintain Backward Compatibility: The default behavior remains unchanged for existing applications, ensuring no breaking changes to the public API.

Example Usage with a Custom Adapter:

import { NgModule } from '@angular/core';
import { DateAdapter } from 'ng-zorro-antd/core/time';
import { JalaliDateAdapter } from './adapters/jalali-date-adapter';

@NgModule({
  providers: [
    { provide: DateAdapter, useClass: JalaliDateAdapter },
  ],
})
export class AppModule { }

---

By introducing the DateAdapter abstraction layer, ng-zorro-antd can enhance its flexibility and internationalization support, allowing developers to meet diverse regional requirements and improve the end-user experience.