[APPS-2255] documentation on date adapters (#9008)

* release note placeholder * datetime docs * fix docs * fix docs
Alfresco · Oct 18, 2023 · cda1273 · cda1273
1 parent d500bc6
commit cda1273
Show file tree

Hide file tree

Showing 2 changed files with 211 additions and 0 deletions.
diff --git a/docs/core/datetime.md b/docs/core/datetime.md
@@ -0,0 +1,156 @@
+# Date and Time
+
+> As of v.6.4.0 the ADF is no longer using `moment.js` for date and time processing.
+> This is related to the `moment.js`` sunset (<https://momentjs.com/docs/?/displaying/format/#/-project-status/>)
+
+## Components
+
+Date and DateTime ADF components are based on the following components:
+
+* Date Picker: <https://v14.material.angular.io/components/datepicker/>
+* DateTime Picker: <https://kuhnroyal.github.io/mat-datetimepicker/>
+
+## Adapters
+
+ADF 6.4.0 and later provides custom date and time adapters for <https://date-fns.org/> library.
+
+### ADF DateFns Adapter
+
+The `AdfDateFnsAdapter` is an implementation of an Angular DateAdapter,
+that provides backwards compatibility with the [moment.js](https://momentjs.com).
+
+The adapter works with both [moment.js](https://momentjs.com) and [date-fns](https://date-fns.org) formats,
+and dynamically translates `moment.js`  formatting tokens to `date-fns`.
+
+In addition, the adapter automatically detects the current locale and switches to the corresponding values.
+
+```ts
+import { DateAdapter, MAT_DATE_FORMATS } from '@angular/material/core';
+import { AdfDateFnsAdapter, ADF_DATE_FORMATS } from '@alfresco/adf-core';
+
+@Component({
+    providers: [
+        { provide: MAT_DATE_FORMATS, useValue: ADF_DATE_FORMATS },
+        { provide: DateAdapter, useClass: AdfDateFnsAdapter }
+    ]
+})
+export class MyComponent() {
+    constructor(private dateAdapter: DateAdapter<Date>) {}
+}
+```
+
+The default set of ADF formats for Date picker components is as following:
+
+```ts
+export const ADF_DATE_FORMATS: MatDateFormats = {
+    parse: {
+        dateInput: 'dd-MM-yyyy'
+    },
+    display: {
+        dateInput: 'dd-MM-yyyy',
+        monthLabel: 'LLL',
+        monthYearLabel: 'LLL uuuu',
+        dateA11yLabel: 'PP',
+        monthYearA11yLabel: 'LLLL uuuu'
+    }
+};
+```
+
+You can provide own format defaults by injecting a different `MAT_DATE_FORMATS` value:
+
+```ts
+@Component({
+    providers: [
+        { provide: MAT_DATE_FORMATS, useValue: MY_CUSTOM_FORMATS }
+    ]
+})
+```
+
+### ADF DateTimeFns Adapter
+
+The `AdfDateTimeFnsAdapter` is an implementation of the `mat-datetimepicker` DateTimeAdapter,
+that provides backwards compatibility with the [moment.js](https://momentjs.com).
+
+The adapter works with both [moment.js](https://momentjs.com) and [date-fns](https://date-fns.org) formats,
+and dynamically translates `moment.js`  formatting tokens to `date-fns`.
+
+In addition, the adapter automatically detects the current locale and switches to the corresponding values.
+
+```ts
+import { DateAdapter, MAT_DATE_FORMATS } from '@angular/material/core';
+import { DatetimeAdapter, MAT_DATETIME_FORMATS } from '@mat-datetimepicker/core';
+import { 
+    ADF_DATE_FORMATS, 
+    ADF_DATETIME_FORMATS, 
+    AdfDateFnsAdapter, 
+    AdfDateTimeFnsAdapter 
+} from '@alfresco/adf-core';
+
+@Component({
+    providers: [
+        { provide: MAT_DATE_FORMATS, useValue: ADF_DATE_FORMATS },
+        { provide: MAT_DATETIME_FORMATS, useValue: ADF_DATETIME_FORMATS },
+        { provide: DateAdapter, useClass: AdfDateFnsAdapter },
+        { provide: DatetimeAdapter, useClass: AdfDateTimeFnsAdapter }
+    ]
+})
+export class MyComponent() {
+    constructor(private dateAdapter: DateAdapter<Date>,
+        private dateTimeAdapter: DatetimeAdapter<Date>) {}
+}
+```
+
+The default set of formatting rules, compared to the `moment.js` equivalents, is as following:
+
+```ts
+export const ADF_DATETIME_FORMATS: MatDatetimeFormats = {
+    parse: {
+        dateInput: 'P', // L
+        monthInput: 'LLLL', // MMMM
+        timeInput: 'p', // LT
+        datetimeInput: 'Pp' // L LT
+    },
+    display: {
+        dateInput: 'P', // L
+        monthInput: 'LLLL', // MMMM
+        datetimeInput: 'Pp', // L LT
+        timeInput: 'p', // LT
+        monthYearLabel: 'LLL uuuu', // MMM YYYY
+        dateA11yLabel: 'PP', // LL
+        monthYearA11yLabel: 'LLLL uuuu', // MMMM YYYY
+        popupHeaderDateLabel: 'ccc, dd MMM' // ddd, DD MMM
+    }
+};
+```
+
+You can provide own format defaults by injecting a different `MAT_DATETIME_FORMATS` value:
+
+```ts
+@Component({
+    providers: [
+        { provide: MAT_DATETIME_FORMATS, useValue: MY_CUSTOM_FORMATS }
+    ]
+})
+```
+
+## Date Utils
+
+If you need lower-level manipulations with dates, ADF provides `DateFnsUtils` that addresses various scenarios like:
+
+- converting `moment.js` format tokens to `date-fns`
+- parsing dates from strings, with moment.js/date-fns formatting tokens
+- formatting dates as strings, using moment.js/date-fns formatting tokens
+- validating dates
+- converting UTC to Local datetime, or Local to UTC
+
+```ts
+import { DateFnsUtils } from '@alfresco/adf-core';
+
+// format using moment.js tokens
+const momentString = DateFnsUtils.formatDate(new Date(), 'll');
+
+// format using date-fns tokens
+const dateFnsString = DateFnsUtils.formatDate(new Date(), 'PP');
+```
+
+You can find more details on the format conversion in the DateFnsUtils [unit tests](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/lib/core/src/lib/common/utils/date-fns-utils.spec.ts).
diff --git a/docs/release-notes/RelNote-6.4.0.md b/docs/release-notes/RelNote-6.4.0.md
@@ -0,0 +1,55 @@
+---
+Title: Release notes v6.3.0
+---
+
+# Alfresco Application Development Framework (ADF) version 6.4.0 Release Note
+
+This document provides information on the Alfresco Application Development Framework **v6.4.0**.
+
+You can find release artifacts on [GitHub](https://github.com/Alfresco/alfresco-ng2-components/releases/tag/6.4.0).
+
+## Contents
+
+- [New Package Versions](#new-package-versions)
+- [Features](#features)
+- [Changelog](#changelog)
+- [See Also](#see-also)
+
+## New Package Versions
+
+| Name                           | Version |
+|--------------------------------|---------|
+| @alfresco/js-api               | 7.1.0   |
+| @alfresco/adf-content-services | 6.4.0   |
+| @alfresco/adf-process-services | 6.4.0   |
+| @alfresco/adf-core             | 6.4.0   |
+| @alfresco/adf-insights         | 6.4.0   |
+| @alfresco/adf-extensions       | 6.4.0   |
+| @alfresco/adf-testing          | 6.4.0   |
+| @alfresco/adf-cli              | 6.4.0   |
+
+## Features
+
+The suggested stack is:
+
+| Name       | Version |
+|------------|---------|
+| Node       | 18.x    |
+| npm        | 8.x     |
+| Angular    | 14.x    |
+| Typescript | 4.7     |
+
+For a complete list of changes, supported browsers and new feature please refer to the official documentation
+
+## Deprecations
+
+- `adfMomentDate` pipe is deprecated and no longer used by ADF components and apps
+- `adfMomentDateTime` pipe is deprecated and no longer used by ADF components and apps
+- custom `MomentDateAdapter` is deprecated and no longer used by ADF components and apps
+
+## Changelog
+
+## See Also
+
+- [Issue Tracker](https://github.com/Alfresco/alfresco-ng2-components/issues/new)
+- [Discussion forum](http://gitter.im/Alfresco/alfresco-ng2-components)