@dxtmisha/wiki 0.24.0 → 0.24.1

package/src/media/functional/ru/useGeoIntlRef.mdx

@@ -0,0 +1,288 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/functional/ru/Composables/useGeoIntlRef'/>
+
+# Композабл useGeoIntlRef
+
+Композабл для создания реактивного объекта интернационализации. Предоставляет методы форматирования чисел, валют, дат и названий с автоматическим учётом локали пользователя. Все методы возвращают computed значения, которые автоматически обновляются при изменении входных данных.
+
+## Основные возможности
+
+- **Форматирование чисел** — локализованное представление чисел с разделителями
+- **Форматирование валют** — отображение денежных сумм с символами валют
+- **Форматирование дат** — различные форматы дат и времени по региональным стандартам
+- **Названия стран и языков** — локализованные названия регионов
+- **Относительное время** — "2 дня назад", "через 5 минут" и т.д.
+- **Проценты и единицы** — форматирование процентов и единиц измерения
+- **Реактивность** — все методы возвращают computed, обновляющиеся автоматически
+- **Автоопределение локали** — использует геолокацию пользователя по умолчанию
+
+## Функция
+
+### `useGeoIntlRef()`
+
+Создаёт и возвращает экземпляр класса `GeoIntlRef` для работы с форматированием данных.
+
+**Параметры:** нет
+
+**Возвращает:** `GeoIntlRef` — объект с методами форматирования
+
+```javascript
+import { useGeoIntlRef } from '@dxtmisha/functional'
+
+// Создание экземпляра
+const intl = useGeoIntlRef()
+
+// Все методы возвращают ComputedRef
+const formatted = intl.number(1234.56)
+```
+
+## Методы форматирования чисел
+
+### `number`
+
+Форматирование числа согласно локали.
+
+**Параметры:**
+- `value: RefOrNormal<NumberOrString>` — число для форматирования
+- `options?: Intl.NumberFormatOptions` — опции форматирования
+
+**Возвращает:** `ComputedRef<string>`
+
+```javascript
+const intl = useGeoIntlRef()
+const count = ref(1234567.89)
+
+intl.number(count) // ComputedRef<'1 234 567,89'>
+intl.number(1000, { minimumFractionDigits: 2 }) // ComputedRef<'1 000,00'>
+```
+
+### `decimal`
+
+Возвращает символ десятичного разделителя для текущей локали.
+
+**Возвращает:** `ComputedRef<string>`
+
+```javascript
+const intl = useGeoIntlRef()
+intl.decimal() // ComputedRef<','>  (для ru-RU)
+               // ComputedRef<'.'>  (для en-US)
+```
+
+### `percent`
+
+Форматирование числа как процента.
+
+**Параметры:**
+- `value: RefOrNormal<NumberOrString>` — число для форматирования (0.15 = 15%)
+- `options?: Intl.NumberFormatOptions` — опции форматирования
+
+**Возвращает:** `ComputedRef<string>`
+
+```javascript
+intl.percent(0.15)  // ComputedRef<'15%'>
+intl.percent(1.25)  // ComputedRef<'125%'>
+```
+
+### `percentBy100`
+
+Форматирование числа как процента (значение уже в процентах).
+
+**Параметры:**
+- `value: RefOrNormal<NumberOrString>` — число для форматирования (15 = 15%)
+- `options?: Intl.NumberFormatOptions` — опции форматирования
+
+**Возвращает:** `ComputedRef<string>`
+
+```javascript
+intl.percentBy100(15)   // ComputedRef<'15%'>
+intl.percentBy100(125)  // ComputedRef<'125%'>
+```
+
+## Методы форматирования валют
+
+### `currency`
+
+Форматирование денежной суммы.
+
+**Параметры:**
+- `value: RefOrNormal<NumberOrString>` — сумма для форматирования
+- `currencyOptions?: RefOrNormal<string | Intl.NumberFormatOptions>` — код валюты или опции
+- `numberOnly?: boolean` — не показывать символ валюты (по умолчанию `false`)
+
+**Возвращает:** `ComputedRef<string>`
+
+```javascript
+const intl = useGeoIntlRef()
+const price = ref(99.99)
+
+intl.currency(price, 'USD')           // ComputedRef<'$99,99'>
+intl.currency(1234.56, 'RUB')         // ComputedRef<'1 234,56 ₽'>
+intl.currency(500, 'EUR', true)       // ComputedRef<'500,00'> (без символа)
+```
+
+### `unit`
+
+Форматирование с единицами измерения.
+
+**Параметры:**
+- `value: RefOrNormal<NumberOrString>` — значение для форматирования
+- `unitOptions?: string | Intl.NumberFormatOptions` — единица измерения или опции
+
+**Возвращает:** `ComputedRef<string>`
+
+```javascript
+intl.unit(100, 'kilometer')  // ComputedRef<'100 км'>
+intl.unit(50, 'kilogram')    // ComputedRef<'50 кг'>
+intl.unit(1.5, 'hour')       // ComputedRef<'1,5 ч'>
+```
+
+## Методы форматирования дат
+
+### `date`
+
+Форматирование даты и времени.
+
+**Параметры:**
+- `value: RefOrNormal<NumberOrStringOrDate>` — дата для форматирования
+- `type?: GeoDate` — тип формата ('date' | 'time' | 'datetime' | 'full' | 'long' | 'medium' | 'short')
+- `styleOptions?: Intl.DateTimeFormatOptions['month'] | Intl.DateTimeFormatOptions` — стиль или опции
+- `hour24?: boolean` — использовать 24-часовой формат
+
+**Возвращает:** `ComputedRef<string>`
+
+```javascript
+const date = ref(new Date('2024-10-15 14:30:00'))
+
+intl.date(date)               // ComputedRef<'15.10.2024'>
+intl.date(date, 'time')       // ComputedRef<'14:30'>
+intl.date(date, 'datetime')   // ComputedRef<'15.10.2024, 14:30'>
+intl.date(date, 'full')       // ComputedRef<'вторник, 15 октября 2024 г.'>
+```
+
+### `relative`
+
+Форматирование относительного времени ("2 дня назад", "через час").
+
+**Параметры:**
+- `value: RefOrNormal<NumberOrStringOrDate>` — дата для сравнения
+- `styleOptions?: Intl.RelativeTimeFormatStyle | Intl.RelativeTimeFormatOptions` — стиль ('long' | 'short' | 'narrow')
+- `todayValue?: Date` — текущая дата (по умолчанию `new Date()`)
+
+**Возвращает:** `ComputedRef<string>`
+
+```javascript
+const twoDaysAgo = new Date()
+twoDaysAgo.setDate(twoDaysAgo.getDate() - 2)
+
+intl.relative(twoDaysAgo)             // ComputedRef<'2 дня назад'>
+intl.relative(twoDaysAgo, 'short')    // ComputedRef<'2 дн. назад'>
+```
+
+### `relativeLimit`
+
+Форматирование относительного времени с ограничением. Если разница превышает лимит, выводится абсолютная дата.
+
+**Параметры:**
+- `value: RefOrNormal<NumberOrStringOrDate>` — дата для форматирования
+- `limit: number` — лимит в днях
+- `todayValue?: Date` — текущая дата
+- `relativeOptions?: Intl.RelativeTimeFormatStyle | Intl.RelativeTimeFormatOptions` — опции относительного формата
+- `dateOptions?: Intl.DateTimeFormatOptions['month'] | Intl.DateTimeFormatOptions` — опции формата даты
+- `type?: GeoDate` — тип формата даты
+- `hour24?: boolean` — 24-часовой формат
+
+**Возвращает:** `ComputedRef<string>`
+
+```javascript
+const threeDaysAgo = new Date()
+threeDaysAgo.setDate(threeDaysAgo.getDate() - 3)
+
+intl.relativeLimit(threeDaysAgo, 7)   // ComputedRef<'3 дня назад'>
+
+const tenDaysAgo = new Date()
+tenDaysAgo.setDate(tenDaysAgo.getDate() - 10)
+
+intl.relativeLimit(tenDaysAgo, 7)     // ComputedRef<'05.10.2024'> (абсолютная дата)
+```
+
+## Методы для названий
+
+### `display`
+
+Получение локализованного названия (языка, региона, скрипта и т.д.).
+
+**Параметры:**
+- `value?: RefOrNormal<string>` — код для получения названия
+- `typeOptions?: Intl.DisplayNamesOptions['type'] | Intl.DisplayNamesOptions` — тип ('language' | 'region' | 'script' | 'currency')
+
+**Возвращает:** `ComputedRef<string>`
+
+```javascript
+intl.display('US', 'region')    // ComputedRef<'США'>
+intl.display('en', 'language')  // ComputedRef<'английский'>
+intl.display('USD', 'currency') // ComputedRef<'доллар США'>
+```
+
+### `languageName`
+
+Получение названия языка.
+
+**Параметры:**
+- `value?: RefOrNormal<string>` — код языка
+- `style?: Intl.RelativeTimeFormatStyle` — стиль отображения
+
+**Возвращает:** `ComputedRef<string>`
+
+```javascript
+intl.languageName('en')  // ComputedRef<'английский'>
+intl.languageName('de')  // ComputedRef<'немецкий'>
+```
+
+### `countryName`
+
+Получение названия страны.
+
+**Параметры:**
+- `value?: RefOrNormal<string>` — код страны
+- `style?: Intl.RelativeTimeFormatStyle` — стиль отображения
+
+**Возвращает:** `ComputedRef<string>`
+
+```javascript
+intl.countryName('US')  // ComputedRef<'США'>
+intl.countryName('GB')  // ComputedRef<'Великобритания'>
+```
+
+## Примеры использования
+
+### Базовое использование
+
+```javascript
+import { ref } from 'vue'
+import { useGeoIntlRef } from '@dxtmisha/functional'
+
+const intl = useGeoIntlRef()
+const price = ref(1234.56)
+
+// Все методы возвращают ComputedRef
+const formatted = intl.currency(price, 'USD')
+console.log(formatted.value) // '$1,234.56'
+
+// Автоматическое обновление при изменении
+price.value = 2000
+console.log(formatted.value) // '$2,000.00'
+```
+
+### Реактивные параметры
+
+```javascript
+const price = ref(100)
+const currency = ref('USD')
+
+// Реактивная валюта и значение
+const formatted = intl.currency(price, currency)
+
+currency.value = 'EUR'
+// formatted.value автоматически обновится
+```

package/src/media/functional/ru/useHashRef.mdx

@@ -0,0 +1,302 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/functional/ru/Composables/useHashRef'/>
+
+# Композабл useHashRef
+
+Композабл для создания реактивной переменной, синхронизированной с URL hash. Автоматически управляет чтением и записью значений в hash часть URL, обеспечивая двустороннюю синхронизацию между реактивным состоянием Vue и параметрами в адресной строке браузера.
+
+## Основные возможности
+
+- **Двусторонняя синхронизация** — автоматическая синхронизация между ref и URL hash
+- **Автоматическое сохранение** — изменения ref автоматически отражаются в URL
+- **Реактивность** — изменения URL hash автоматически обновляют ref
+- **Кеширование экземпляров** — переиспользование ref для одинаковых имён параметров
+- **Типобезопасность** — полная поддержка TypeScript с дженериками
+- **Значения по умолчанию** — поддержка начальных значений и функций-фабрик
+- **Автоматическая инициализация** — загрузка существующих значений из URL при создании
+
+## Функция
+
+### `useHashRef`
+
+Создаёт реактивную переменную, синхронизированную с параметром в URL hash.
+
+**Параметры:**
+- `name: string` — имя параметра в hash URL
+- `defaultValue?: T | (() => T)` — значение по умолчанию или функция для его генерации (опционально)
+
+**Возвращает:** `Ref<T>` — реактивная переменная Vue, связанная с hash параметром
+
+```javascript
+import { useHashRef } from '@dxtmisha/functional'
+
+// Простое использование без значения по умолчанию
+const currentTab = useHashRef('tab')
+console.log(currentTab.value) // undefined (если hash пустой)
+
+// С значением по умолчанию
+const activeView = useHashRef('view', 'grid')
+console.log(activeView.value) // 'grid' (если hash не содержит 'view')
+
+// С функцией-фабрикой для значения по умолчанию
+const userId = useHashRef('userId', () => Math.floor(Math.random() * 1000))
+```
+
+## Основное использование
+
+### Базовая синхронизация
+
+```javascript
+import { useHashRef } from '@dxtmisha/functional'
+
+// Создание ref, синхронизированного с hash
+const currentPage = useHashRef('page', 1)
+
+// При изменении ref - URL автоматически обновляется
+currentPage.value = 2
+// URL: #page=2
+
+currentPage.value = 5
+// URL: #page=5
+
+// При изменении URL вручную - ref автоматически обновляется
+// Пользователь меняет URL на: #page=10
+console.log(currentPage.value) // 10
+```
+
+### Работа с несколькими параметрами
+
+```javascript
+// Несколько независимых hash параметров
+const searchQuery = useHashRef('q', '')
+const sortOrder = useHashRef('sort', 'asc')
+const pageNumber = useHashRef('page', 1)
+
+searchQuery.value = 'vue композаблы'
+sortOrder.value = 'desc'
+pageNumber.value = 3
+
+// URL: #q=vue композаблы;sort=desc;page=3
+
+// Все параметры остаются синхронизированными
+console.log(searchQuery.value) // 'vue композаблы'
+console.log(sortOrder.value)   // 'desc'
+console.log(pageNumber.value)  // 3
+```
+
+### Кеширование экземпляров
+
+```javascript
+// При повторном вызове с тем же именем возвращается существующий ref
+const tab1 = useHashRef('activeTab', 'home')
+const tab2 = useHashRef('activeTab', 'profile')
+
+console.log(tab1 === tab2) // true - тот же ref
+
+tab1.value = 'settings'
+console.log(tab2.value) // 'settings' - оба указывают на один ref
+```
+
+## Использование в компонентах
+
+### Управление табами
+
+```javascript
+import { useHashRef } from '@dxtmisha/functional'
+
+export default {
+  setup() {
+    const activeTab = useHashRef('tab', 'overview')
+
+    return {
+      activeTab,
+      tabs: ['overview', 'details', 'settings']
+    }
+  }
+}
+
+// Template:
+// <div>
+//   <button
+//     v-for="tab in tabs"
+//     :key="tab"
+//     @click="activeTab = tab"
+//     :class="{ active: activeTab === tab }"
+//   >
+//     {{ tab }}
+//   </button>
+// </div>
+```
+
+### Пагинация с сохранением состояния
+
+```javascript
+import { computed } from 'vue'
+import { useHashRef } from '@dxtmisha/functional'
+
+export default {
+  setup() {
+    const currentPage = useHashRef('page', 1)
+    const itemsPerPage = 20
+    const totalItems = 100
+
+    const totalPages = computed(() =>
+      Math.ceil(totalItems / itemsPerPage)
+    )
+
+    const nextPage = () => {
+      if (currentPage.value < totalPages.value) {
+        currentPage.value++
+      }
+    }
+
+    const prevPage = () => {
+      if (currentPage.value > 1) {
+        currentPage.value--
+      }
+    }
+
+    return {
+      currentPage,
+      totalPages,
+      nextPage,
+      prevPage
+    }
+  }
+}
+```
+
+### Фильтры и поиск
+
+```javascript
+import { watch } from 'vue'
+import { useHashRef } from '@dxtmisha/functional'
+
+export default {
+  setup() {
+    const searchQuery = useHashRef('q', '')
+    const category = useHashRef('category', 'all')
+    const sortBy = useHashRef('sort', 'date')
+
+    // Отслеживание изменений для загрузки данных
+    watch([searchQuery, category, sortBy], () => {
+      console.log('Загрузка данных с параметрами:')
+      console.log('Поиск:', searchQuery.value)
+      console.log('Категория:', category.value)
+      console.log('Сортировка:', sortBy.value)
+      // Здесь выполняется запрос к API
+    })
+
+    return {
+      searchQuery,
+      category,
+      sortBy
+    }
+  }
+}
+```
+
+## Работа с типами данных
+
+### Числовые значения
+
+```javascript
+// Hash автоматически преобразует типы
+const pageNumber = useHashRef<number>('page', 1)
+
+pageNumber.value = 5
+// URL: #page=5
+
+// При загрузке из URL строка автоматически преобразуется
+// URL: #page=10
+console.log(typeof pageNumber.value) // 'number'
+console.log(pageNumber.value)        // 10
+```
+
+### Булевы значения
+
+```javascript
+const isActive = useHashRef<boolean>('active', false)
+
+isActive.value = true
+// URL: #active=true
+
+// Автоматическое преобразование из строки
+// URL: #active=false
+console.log(typeof isActive.value) // 'boolean'
+console.log(isActive.value)        // false
+```
+
+### Объекты и массивы
+
+```javascript
+// Для сложных типов используется сериализация
+const filters = useHashRef('filters', { min: 0, max: 100 })
+
+filters.value = { min: 20, max: 80 }
+// URL будет содержать сериализованное представление
+
+// Значения восстанавливаются при загрузке
+console.log(filters.value) // { min: 20, max: 80 }
+```
+
+## Интеграция с классом Hash
+
+Композабл использует класс `Hash` для управления URL hash:
+
+```javascript
+import { Hash } from '@dxtmisha/functional'
+
+// Прямое использование класса
+Hash.set('tab', 'profile')
+console.log(Hash.get('tab')) // 'profile'
+
+// useHashRef автоматически синхронизируется с Hash
+const tab = useHashRef('tab')
+console.log(tab.value) // 'profile'
+
+// Изменения через Hash отражаются в ref
+Hash.set('tab', 'settings')
+console.log(tab.value) // 'settings'
+```
+
+## Примеры использования
+
+### Сохранение состояния формы
+
+```javascript
+const formData = {
+  name: useHashRef('name', ''),
+  email: useHashRef('email', ''),
+  role: useHashRef('role', 'user')
+}
+
+// При заполнении формы состояние сохраняется в URL
+formData.name.value = 'Иван'
+formData.email.value = 'ivan@example.com'
+formData.role.value = 'admin'
+
+// URL: #name=Иван;email=ivan@example.com;role=admin
+
+// При перезагрузке страницы состояние восстанавливается
+```
+
+### Управление модальными окнами
+
+```javascript
+const modalOpen = useHashRef('modal', null)
+
+const openModal = (modalName) => {
+  modalOpen.value = modalName
+  // URL: #modal=confirmation
+}
+
+const closeModal = () => {
+  modalOpen.value = null
+  // URL: #modal=null или hash очищается
+}
+
+// Кнопка "Назад" в браузере закрывает модальное окно
+```
+