Add initial project files

2026-09-01 13:03:41 +03:00
parent 22e111bb44
commit 74cb5b6176
1841 changed files with 242819 additions and 30 deletions
@@ -0,0 +1,143 @@
+# [←](../../../docs/README.md) @crux-kit/intl-date
+
+Конфігурація форматів дат, парсинг, форматування
+
+## Як використовувати
+
+### Ініціалізація сервісу
+
+```ts
+import { intlDateService, EN_LOCALE, UK_LOCALE } from '@crux-kit/intl-date';
+export const IntlDate = intlDateService(
+  {
+    localeMap: {
+      en: {
+        code: "enUS",
+        locale: EN_LOCALE,
+        displayFormats: {
+          DATE: 'yyyy-MM-dd',
+          ...
+        }
+      },
+      uk: {
+        code: "uk",
+        locale: UK_LOCALE,
+      },
+    },
+    language: "uk",
+  },
+  console
+);
+```
+
+1. `localeMap` - Налаштовує локалі
+
+```ts
+    /*
+        код береться з бібліотеки date-fns
+        import { enUS } from "date-fns/locale";
+        code: enUS.code
+    */
+    code: "enUS",
+    /*
+        locale береться з бібліотеки date-fns
+        import { enUS } from "date-fns/locale";
+        locale: enUS
+    */
+    locale: EN_LOCALE,
+    /*
+        displayFormats перезаписує дефолтні формати відображення дати для конкретної мови
+    */
+    displayFormats: {
+        DATE: 'yyyy-MM-dd',
+        ...
+    }
+```
+
+2. `language` - дефолтна мова
+
+3. `displayFormat` - базовий формат відображення дати. Можна перезаписувати лише окремі поля
+
+```ts
+export default {
+  DAY_WITH_STRING_MONTH: 'dd MMMM',
+  DAY_WITH_STRING_SHORT_MONTH: 'dd MMM',
+  DATE: 'dd.MM.yyyy',
+  DATE_WITH_STRING_SHORT_MONTH: 'dd MMM yyyy',
+  DATE_WITH_STRING_MONTH: 'dd MMMM yyyy',
+  DATE_TIME: 'dd.MM.yyyy hh:mm a',
+  DATE_TIME_WITH_SECONDS: 'dd.MM.yyyy HH:mm:ss',
+  DATE_TIME_WITH_STRING_MONTH: 'dd MMMM yyyy HH:mm',
+  DATE_TIME_WITH_STRING_MONTH_WITH_SECONDS: 'dd MMMM yyyy HH:mm:ss',
+  DATE_TIME_WITH_STRING_SHORT_MONTH: 'dd MMM yyyy HH:mm',
+  DATE_TIME_WITH_STRING_SHORT_MONTH_WITH_SECONDS: 'dd MMM yyyy HH:mm:ss',
+  TIME: 'HH:mm',
+  TIME_WITH_SECONDS: 'HH:mm:ss',
+  YEAR: 'yyyy',
+  HOURS: 'HH',
+  SHORT_HOURS: 'H',
+  MINUTES: 'mm',
+  SHORT_MINUTES: 'm',
+  UNIVERSAL_ISO: 'UNIVERSAL_ISO',
+};
+```
+
+4. `sourceFormat` - базові формати, що використовуються при парсингу зовнішніх даних API, form values і тд
+
+```ts
+export default {
+  DATE: 'yyyy-MM-dd',
+  UNIVERSAL_ISO: 'UNIVERSAL_ISO',
+  TIME: 'HH:mm',
+  TIME_WITH_SECONDS: 'HH:mm:ss',
+  DATE_TIME: 'yyyy-MM-dd HH:mm',
+  DATE_TIME_WITH_SECONDS: 'yyyy-MM-dd HH:mm:ss',
+  MINUTES_WITH_SECONDS: 'mm:ss',
+};
+```
+
+### Форматування дати
+
+```ts
+const date = '2025-11-27T13:17:02.174Z';
+
+// "27 листопада 2025 13:17:02"
+IntlDate.parseSource(date, 'UNIVERSAL_ISO').formatToDisplay('DATE_TIME_WITH_STRING_MONTH_WITH_SECONDS');
+
+// "27 листопада 2025 15:17:02"
+IntlDate.parseSource(date, 'UNIVERSAL_ISO').formatToDisplay('DATE_TIME_WITH_STRING_MONTH_WITH_SECONDS', { displayLocal: true });
+```
+
+### Зміна мови
+
+```ts
+IntlDate.setLocaleGlobally('en');
+```
+
+Усі формати дати після цього підуть по новій локалі.
+Потрібно щоб локаль була у `localeMap`!!!
+
+### Додаткові можливості
+
+#### Мутація дати
+
+додати/відняти дату/час від поточної дати
+
+```ts
+const display = IntlDate.parseSource(date, 'UNIVERSAL_ISO')
+  .subtract(2, 'years')
+  .add(2, 'days')
+  .formatToDisplay('DATE_TIME_WITH_STRING_MONTH_WITH_SECONDS', {
+    displayLocal: true,
+  });
+
+type ManipulateUnit = 'years' | 'months' | 'weeks' | 'days' | 'hours' | 'minutes' | 'seconds';
+```
+
+#### Мова
+
+Попередньо налаштовані Укранська, Польська, Англійська мови
+
+```ts
+import { EN_LOCALE_CONFIG, UK_LOCALE_CONFIG, PL_LOCALE_CONFIG } from '@crux-kit/intl-date';
+```