refactor: return calendarFormats and make them optional everywhere

docusaurus/docs/React/guides/date-time-formatting.mdx

@@ -37,9 +37,26 @@ export type TimestampFormatterOptions = {
 };
 ```
 
-If calendar formatting is enabled, the dates are formatted with time-relative words ("yesterday at ...", "last ..."). The calendar strings can be further customized with `calendarFormats` object. It also means that the `format` prop would be ignored. On the other hand, if calendar is disabled, then `calendarFormats` is ignored and `format` string is applied.
+If calendar formatting is enabled, the dates are formatted with time-relative words ("yesterday at ...", "last ..."). The calendar strings can be further customized with `calendarFormats` object. The `calendarFormats` object has to cover all the formatting cases as shows the example below:
 
-All the components can be overridden through `Channel` component context
+```
+{
+  lastDay: '[gestern um] LT',
+  lastWeek: '[letzten] dddd [um] LT',
+  nextDay: '[morgen um] LT',
+  nextWeek: 'dddd [um] LT',
+  sameDay: '[heute um] LT',
+  sameElse: 'L',
+}
+```
+
+:::important
+If any of the `calendarFormats` keys are missing, then the underlying library will fall back to hard-coded english equivalents
+:::
+
+If `calendar` formatting is enabled, the `format` prop would be ignored. So to apply the `format` string, the `calendar` has to be disabled (applies to `DateSeparator` and `MessageTimestamp`.
+
+All the components can be overridden through `Channel` component context:
 
 ```tsx
 import {
@@ -57,7 +74,7 @@ const CustomDateSeparator = (props: DateSeparatorProps) => (
 );
 
 const SystemMessage = (props: EventComponentProps) => (
-  <EventComponent {...props} calendar={false} format={'YYYY'} /> // calendar is enabled by default
+  <EventComponent {...props} format={'YYYY'} /> // calendar is disabled by default
 );
 
 const CustomMessageTimestamp = (props: MessageTimestampProps) => (
@@ -88,7 +105,7 @@ By default, the function is consumed by the `MessageTimestamp` component. This m
 
 ### Date & time formatting with i18n service
 
-Until now, the datetime values could be customized within `Channel` at best. Formatting via i18n service allows for SDK wide configuration. The configuration is stored with other translations in JSON files. Formatting with i18n service has the following advantages:
+Until now, the datetime values could be customized within the `Channel` component at best. Formatting via i18n service allows for SDK wide configuration. The configuration is stored with other translations in JSON files. Formatting with i18n service has the following advantages:
 
 - it is centralized
 - it takes into consideration the locale out of the box
@@ -102,9 +119,9 @@ The default datetime formatting configuration is stored in the JSON translation
 
 ##### Overriding the prop defaults
 
-The default date and time rendering components in the SDK were created with default prop values that override the configuration parameters provided over JSON translations. Therefore, if we wanted to configure the formatting from JSON translation files, we need to nullify the prop defaults. An example follows:
+The default date and time rendering components in the SDK were created with default prop values that override the configuration parameters provided over JSON translations. Therefore, if we wanted to configure the formatting from JSON translation files, we need to nullify the prop defaults first. An example follows:
 
-```jsx
+```tsx
 import {
   DateSeparatorProps,
   DateSeparator,
@@ -127,7 +144,13 @@ const CustomMessageTimestamp = (props: MessageTimestampProps) => (
 );
 ```
 
-Besides overriding the formatting parameters above, we can customize the translation key via `timestampTranslationKey` prop all the above components (`DateSeparator`, `EventComponent`, `Timestamp`).
+Now we can apply custom configuration in all the translation JSON files. It could look similar to the following example key-value pair.
+
+```
+"timestamp/SystemMessage": "{{ timestamp, timestampFormatter(format: YYYY) }}",
+```
+
+Besides overriding the formatting parameters above, we can customize the translation key via `timestampTranslationKey` prop all the above components (`DateSeparator`, `EventComponent`, `MessageTimestamp`).
 
 ```tsx
 import { MessageTimestampProps, MessageTimestamp } from 'stream-chat-react';
@@ -139,10 +162,10 @@ const CustomMessageTimestamp = (props: MessageTimestampProps) => (
 
 ##### Understanding the formatting syntax
 
-Once the default prop values are nullified, we override the default formatting rules in the JSON translation value. We can take a look at an example:
+Once the default prop values are nullified, we override the default formatting rules in the JSON translation value. We can take a look at an example of German translation for SystemMessage:
 
 ```
-"timestamp/SystemMessage": "{{ timestamp, timestampFormatter(calendar: true; calendarFormats: {\"sameElse\": \"dddd L\"}) }}",
+"timestamp/SystemMessage": "{{ timestamp, timestampFormatter(calendar: true; calendarFormats: {\"lastDay: \"[gestern um] LT\", \"lastWeek\": \"[letzten] dddd [um] LT\", \"nextDay\": \"[morgen um] LT\", \"nextWeek\": \"dddd [um] LT\", \"sameDay\": \"[heute um] LT\", \"sameElse\": \"L\"}) }}",
 ```
 
 Let's dissect the example:

docusaurus/sidebars-react.json

@@ -140,7 +140,8 @@
         "guides/typescript_and_generics",
         "guides/channel_read_state",
         "guides/video-integration/video-integration-stream",
-        "guides/sdk-state-management"
+        "guides/sdk-state-management",
+        "guides/date-time-formatting"
       ]
     },
     { "Release Guides": ["release-guides/upgrade-to-v10", "release-guides/upgrade-to-v11"] },

src/components/EventComponent/EventComponent.tsx

@@ -29,9 +29,9 @@ const UnMemoizedEventComponent = <
   props: EventComponentProps<StreamChatGenerics>,
 ) => {
   const {
-    calendar = true,
-    calendarFormats = { sameElse: 'dddd L' },
-    format,
+    calendar,
+    calendarFormats,
+    format = 'dddd L',
     Avatar = DefaultAvatar,
     message,
     timestampTranslationKey = 'timestamp/SystemMessage',

src/i18n/de.json

@@ -123,7 +123,7 @@
   "searchResultsCount_other": "{{ count }} Ergebnisse",
   "this content could not be displayed": "Dieser Inhalt konnte nicht angezeigt werden",
   "timestamp/DateSeparator": "{{ timestamp, timestampFormatter(calendar: true) }}",
-  "timestamp/SystemMessage": "{{ timestamp, timestampFormatter(calendar: true; calendarFormats: {\"sameElse\": \"dddd L\"}) }}",
+  "timestamp/SystemMessage": "{{ timestamp, timestampFormatter(format: dddd L) }}",
   "timestamp/MessageTimestamp": "{{ timestamp, timestampFormatter(calendar: true; format: h:mmA) }}",
   "unban-command-args": "[@Benutzername]",
   "unban-command-description": "Einen Benutzer entbannen",

src/i18n/en.json

@@ -117,7 +117,7 @@
   "searchResultsCount_other": "{{ count }} results",
   "this content could not be displayed": "this content could not be displayed",
   "timestamp/DateSeparator": "{{ timestamp, timestampFormatter(calendar: true) }}",
-  "timestamp/SystemMessage": "{{ timestamp, timestampFormatter(calendar: true; calendarFormats: {\"sameElse\": \"dddd L\"}) }}",
+  "timestamp/SystemMessage": "{{ timestamp, timestampFormatter(format: dddd L) }}",
   "timestamp/MessageTimestamp": "{{ timestamp, timestampFormatter(calendar: true; format: h:mmA) }}",
   "unreadMessagesSeparatorText_one": "1 unread message",
   "unreadMessagesSeparatorText_other": "{{count}} unread messages",

src/i18n/es.json

@@ -125,7 +125,7 @@
   "searchResultsCount_other": "{{ count }} resultados",
   "this content could not be displayed": "este contenido no se pudo mostrar",
   "timestamp/DateSeparator": "{{ timestamp, timestampFormatter(calendar: true) }}",
-  "timestamp/SystemMessage": "{{ timestamp, timestampFormatter(calendar: true; calendarFormats: {\"sameElse\": \"dddd L\"}) }}",
+  "timestamp/SystemMessage": "{{ timestamp, timestampFormatter(format: dddd L) }}",
   "timestamp/MessageTimestamp": "{{ timestamp, timestampFormatter(calendar: true; format: h:mmA) }}",
   "unban-command-args": "[@usuario]",
   "unban-command-description": "Quitar la prohibición a un usuario",

src/i18n/fr.json

@@ -125,7 +125,7 @@
   "searchResultsCount_other": "{{ count }} résultats",
   "this content could not be displayed": "ce contenu n'a pu être affiché",
   "timestamp/DateSeparator": "{{ timestamp, timestampFormatter(calendar: true) }}",
-  "timestamp/SystemMessage": "{{ timestamp, timestampFormatter(calendar: true; calendarFormats: {\"sameElse\": \"dddd L\"}) }}",
+  "timestamp/SystemMessage": "{{ timestamp, timestampFormatter(format: dddd L) }}",
   "timestamp/MessageTimestamp": "{{ timestamp, timestampFormatter(calendar: true; format: h:mmA) }}",
   "unban-command-args": "[@nomdutilisateur]",
   "unban-command-description": "Débannir un utilisateur",

src/i18n/hi.json

@@ -124,7 +124,7 @@
   "searchResultsCount_other": "{{ count }} परिणाम",
   "this content could not be displayed": "यह कॉन्टेंट लोड नहीं हो पाया",
   "timestamp/DateSeparator": "{{ timestamp, timestampFormatter(calendar: true) }}",
-  "timestamp/SystemMessage": "{{ timestamp, timestampFormatter(calendar: true; calendarFormats: {\"sameElse\": \"dddd L\"}) }}",
+  "timestamp/SystemMessage": "{{ timestamp, timestampFormatter(format: dddd L) }}",
   "timestamp/MessageTimestamp": "{{ timestamp, timestampFormatter(calendar: true; format: h:mmA) }}",
   "unban-command-args": "[@उपयोगकर्तनाम]",
   "unban-command-description": "एक उपयोगकर्ता को प्रतिषेध से मुक्त करें",

src/i18n/it.json

@@ -125,7 +125,7 @@
   "searchResultsCount_other": "{{ count }} risultati",
   "this content could not be displayed": "questo contenuto non puó essere mostrato",
   "timestamp/DateSeparator": "{{ timestamp, timestampFormatter(calendar: true) }}",
-  "timestamp/SystemMessage": "{{ timestamp, timestampFormatter(calendar: true; calendarFormats: {\"sameElse\": \"dddd L\"}) }}",
+  "timestamp/SystemMessage": "{{ timestamp, timestampFormatter(format: dddd L) }}",
   "timestamp/MessageTimestamp": "{{ timestamp, timestampFormatter(calendar: true; format: h:mmA) }}",
   "unban-command-args": "[@nomeutente]",
   "unban-command-description": "Togliere il divieto a un utente",

src/i18n/ja.json

@@ -123,7 +123,7 @@
   "searchResultsCount_other": "{{ count }}件の結果",
   "this content could not be displayed": "このコンテンツは表示できませんでした",
   "timestamp/DateSeparator": "{{ timestamp, timestampFormatter(calendar: true) }}",
-  "timestamp/SystemMessage": "{{ timestamp, timestampFormatter(calendar: true; calendarFormats: {\"sameElse\": \"dddd L\"}) }}",
+  "timestamp/SystemMessage": "{{ timestamp, timestampFormatter(format: dddd L) }}",
   "timestamp/MessageTimestamp": "{{ timestamp, timestampFormatter(calendar: true; format: h:mmA) }}",
   "unban-command-args": "[@ユーザ名]",
   "unban-command-description": "ユーザーの禁止を解除する",

src/i18n/ko.json

@@ -123,7 +123,7 @@
   "searchResultsCount_other": "{{ count }}개 결과",
   "this content could not be displayed": "이 콘텐츠를 표시할 수 없습니다",
   "timestamp/DateSeparator": "{{ timestamp, timestampFormatter(calendar: true) }}",
-  "timestamp/SystemMessage": "{{ timestamp, timestampFormatter(calendar: true; calendarFormats: {\"sameElse\": \"dddd L\"}) }}",
+  "timestamp/SystemMessage": "{{ timestamp, timestampFormatter(format: dddd L) }}",
   "timestamp/MessageTimestamp": "{{ timestamp, timestampFormatter(calendar: true; format: h:mmA) }}",
   "unban-command-args": "[@사용자이름]",
   "unban-command-description": "사용자 차단 해제",

src/i18n/nl.json

@@ -123,7 +123,7 @@
   "searchResultsCount_other": "{{ count }} resultaten",
   "this content could not be displayed": "Deze inhoud kan niet weergegeven worden",
   "timestamp/DateSeparator": "{{ timestamp, timestampFormatter(calendar: true) }}",
-  "timestamp/SystemMessage": "{{ timestamp, timestampFormatter(calendar: true; calendarFormats: {\"sameElse\": \"dddd L\"}) }}",
+  "timestamp/SystemMessage": "{{ timestamp, timestampFormatter(format: dddd L) }}",
   "timestamp/MessageTimestamp": "{{ timestamp, timestampFormatter(calendar: true; format: h:mmA) }}",
   "unban-command-args": "[@gebruikersnaam]",
   "unban-command-description": "Een gebruiker debannen",

src/i18n/pt.json

@@ -125,7 +125,7 @@
   "searchResultsCount_other": "{{ count }} resultados",
   "this content could not be displayed": "este conteúdo não pôde ser exibido",
   "timestamp/DateSeparator": "{{ timestamp, timestampFormatter(calendar: true) }}",
-  "timestamp/SystemMessage": "{{ timestamp, timestampFormatter(calendar: true; calendarFormats: {\"sameElse\": \"dddd L\"}) }}",
+  "timestamp/SystemMessage": "{{ timestamp, timestampFormatter(format: dddd L) }}",
   "timestamp/MessageTimestamp": "{{ timestamp, timestampFormatter(calendar: true; format: h:mmA) }}",
   "unban-command-args": "[@nomedeusuário]",
   "unban-command-description": "Desbanir um usuário",

src/i18n/ru.json

@@ -127,7 +127,7 @@
   "searchResultsCount_other": "{{ count }} результатов",
   "this content could not be displayed": "Этот контент не может быть отображен в данный момент",
   "timestamp/DateSeparator": "{{ timestamp, timestampFormatter(calendar: true) }}",
-  "timestamp/SystemMessage": "{{ timestamp, timestampFormatter(calendar: true; calendarFormats: {\"sameElse\": \"dddd L\"}) }}",
+  "timestamp/SystemMessage": "{{ timestamp, timestampFormatter(format: dddd L) }}",
   "timestamp/MessageTimestamp": "{{ timestamp, timestampFormatter(calendar: true; format: h:mmA) }}",
   "unban-command-args": "[@имяпользователя]",
   "unban-command-description": "Разблокировать пользователя",

src/i18n/tr.json

@@ -123,7 +123,7 @@
   "searchResultsCount_other": "{{ count }} sonuç",
   "this content could not be displayed": "bu içerik gösterilemiyor",
   "timestamp/DateSeparator": "{{ timestamp, timestampFormatter(calendar: true) }}",
-  "timestamp/SystemMessage": "{{ timestamp, timestampFormatter(calendar: true; calendarFormats: {\"sameElse\": \"dddd L\"}) }}",
+  "timestamp/SystemMessage": "{{ timestamp, timestampFormatter(format: dddd L) }}",
   "timestamp/MessageTimestamp": "{{ timestamp, timestampFormatter(calendar: true; format: h:mmA) }}",
   "unban-command-args": "[@kullanıcıadı]",
   "unban-command-description": "Bir kullanıcının yasağını kaldır",