@dxtmisha/wiki 0.24.0 → 0.24.1

package/src/media/functional/en/useTranslateRef.mdx

@@ -0,0 +1,312 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/functional/en/Composables/useTranslateRef'/>
+
+# Composable useTranslateRef
+
+Composable for getting translated texts by array of keys or string with key. Provides reactive variable that automatically updates when application language changes. Supports dynamic loading of translations from server and text templating with value substitution.
+
+## Key Features
+
+- **Reactive translations** — automatic updates when language changes
+- **Batch loading** — fetch multiple translations at once
+- **Dynamic loading** — automatic loading of missing translations from server
+- **Templating** — value substitution in translation text
+- **Synchronous fallback** — instant return of key before translation loads
+- **Type safety** — full TypeScript support with automatic type inference
+- **Request optimization** — request batching to server (160ms timeout)
+- **Geo integration** — automatic language detection from geolocation
+
+## Function
+
+### `useTranslateRef`
+
+Creates reactive variable with translations by array of keys.
+
+**Parameters:**
+- `names: (string | string[])[]` — array of translation keys or arrays with key and template parameters
+
+**Returns:** `ShallowRef<TranslateList<T>>` — reactive object with translations
+
+```javascript
+import { useTranslateRef } from '@dxtmisha/functional'
+
+// Simple translation
+const texts = useTranslateRef(['hello', 'goodbye', 'welcome'])
+console.log(texts.value.hello) // 'Hello'
+console.log(texts.value.goodbye) // 'Goodbye'
+
+// With templating
+const messages = useTranslateRef([
+  ['greeting', 'John'],
+  ['count', '5']
+])
+console.log(messages.value.greeting) // 'Hello, John!'
+console.log(messages.value.count) // 'Found: 5 items'
+```
+
+### `t` (alias)
+
+Short alias for `useTranslateRef`.
+
+**Parameters:**
+- `names: string[]` — array of translation keys
+
+**Returns:** `ShallowRef<TranslateList<T>>` — reactive object with translations
+
+```javascript
+import { t } from '@dxtmisha/functional'
+
+// Short notation
+const texts = t(['save', 'cancel', 'delete'])
+console.log(texts.value.save) // 'Save'
+```
+
+## Basic Usage
+
+### Basic Translation
+
+```javascript
+import { useTranslateRef } from '@dxtmisha/functional'
+
+// Get multiple translations
+const translations = useTranslateRef([
+  'button.save',
+  'button.cancel',
+  'message.success'
+])
+
+// Access translations
+console.log(translations.value['button.save']) // 'Save'
+console.log(translations.value['button.cancel']) // 'Cancel'
+console.log(translations.value['message.success']) // 'Success!'
+
+// Automatic update on language change
+// Geo.setLocation('ru-RU')
+// translations.value['button.save'] === 'Сохранить'
+```
+
+### Using `t` alias
+
+```javascript
+import { t } from '@dxtmisha/functional'
+
+// Short notation for translations
+const texts = t(['home', 'about', 'contact'])
+
+console.log(texts.value.home) // 'Home'
+console.log(texts.value.about) // 'About'
+console.log(texts.value.contact) // 'Contact'
+```
+
+## Usage in Components
+
+### Basic Form
+
+```javascript
+import { useTranslateRef } from '@dxtmisha/functional'
+
+export default {
+  setup() {
+    const t = useTranslateRef([
+      'form.name',
+      'form.email',
+      'form.submit',
+      'form.reset'
+    ])
+
+    return { t }
+  }
+}
+
+// Template:
+// <form>
+//   <input :placeholder="t['form.name']" />
+//   <input :placeholder="t['form.email']" />
+//   <button>{{ t['form.submit'] }}</button>
+//   <button type="reset">{{ t['form.reset'] }}</button>
+// </form>
+```
+
+### Navigation Menu
+
+```javascript
+import { t } from '@dxtmisha/functional'
+
+export default {
+  setup() {
+    const menu = t([
+      'menu.home',
+      'menu.products',
+      'menu.services',
+      'menu.contact'
+    ])
+
+    return { menu }
+  }
+}
+
+// Template:
+// <nav>
+//   <a href="/">{{ menu['menu.home'] }}</a>
+//   <a href="/products">{{ menu['menu.products'] }}</a>
+//   <a href="/services">{{ menu['menu.services'] }}</a>
+//   <a href="/contact">{{ menu['menu.contact'] }}</a>
+// </nav>
+```
+
+## Text Templating
+
+### Value Substitution
+
+```javascript
+import { useTranslateRef } from '@dxtmisha/functional'
+
+// Translations with parameters
+// Translation file: { "greeting": "Hello, {0}!", "items": "Found {0} of {1}" }
+const messages = useTranslateRef([
+  ['greeting', 'John'],
+  ['items', '5', '10']
+])
+
+console.log(messages.value.greeting) // 'Hello, John!'
+console.log(messages.value.items) // 'Found 5 of 10'
+```
+
+### Dynamic Parameters
+
+```javascript
+import { ref, computed } from 'vue'
+import { useTranslateRef } from '@dxtmisha/functional'
+
+export default {
+  setup() {
+    const userName = ref('John')
+    const count = ref(5)
+
+    // Base translations
+    const t = useTranslateRef(['welcome', 'total'])
+
+    // Dynamic substitution in template
+    const welcomeMessage = computed(() =>
+      t.value.welcome.replace('{0}', userName.value)
+    )
+
+    const totalMessage = computed(() =>
+      t.value.total.replace('{0}', count.value)
+    )
+
+    return { welcomeMessage, totalMessage }
+  }
+}
+```
+
+## Automatic Update on Language Change
+
+```javascript
+import { watch } from 'vue'
+import { useTranslateRef } from '@dxtmisha/functional'
+import { Geo } from '@dxtmisha/functional'
+
+// Translations automatically update on language change
+const texts = useTranslateRef(['title', 'description'])
+
+console.log(texts.value.title) // 'Title' (en-US)
+
+// Change language
+Geo.setLocation('ru-RU')
+
+// texts.value automatically updates
+// texts.value.title === 'Заголовок'
+
+// Can track changes
+watch(() => texts.value, (newTranslations) => {
+  console.log('Translations updated:', newTranslations)
+})
+```
+
+## Integration with Translate Class
+
+Composable uses `Translate` class for translation management:
+
+```javascript
+import { Translate } from '@dxtmisha/functional'
+
+// Set URL for loading translations
+Translate.setUrl('/api/translations')
+
+// Set request parameter name
+Translate.setPropsName('keys')
+
+// Add translations manually (for SSR or tests)
+Translate.addSync({
+  'button.save': 'Save',
+  'button.cancel': 'Cancel'
+})
+
+// Get single translation
+const text = await Translate.get('button.save')
+console.log(text) // 'Save'
+
+// Synchronous get
+const syncText = Translate.getSync('button.save')
+console.log(syncText) // 'Save'
+```
+
+## Usage Examples
+
+### Data Table
+
+```javascript
+const table = useTranslateRef([
+  'table.name',
+  'table.email',
+  'table.status',
+  'table.actions'
+])
+
+// In template:
+// <thead>
+//   <th>{{ table['table.name'] }}</th>
+//   <th>{{ table['table.email'] }}</th>
+//   <th>{{ table['table.status'] }}</th>
+//   <th>{{ table['table.actions'] }}</th>
+// </thead>
+```
+
+### Validation Messages
+
+```javascript
+const validation = useTranslateRef([
+  'validation.required',
+  'validation.email',
+  'validation.minLength',
+  'validation.maxLength'
+])
+
+const validateField = (value) => {
+  if (!value) return validation.value['validation.required']
+  if (value.length < 3) return validation.value['validation.minLength']
+  return null
+}
+```
+
+### Dynamic Content
+
+```javascript
+import { computed } from 'vue'
+
+const status = ref('pending')
+const messages = useTranslateRef([
+  'status.pending',
+  'status.approved',
+  'status.rejected'
+])
+
+const statusText = computed(() =>
+  messages.value[`status.${status.value}`]
+)
+
+console.log(statusText.value) // 'Pending' (when status = 'pending')
+```
+

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

@@ -0,0 +1,55 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/functional/ru/About'/>
+
+# @dxtmisha/functional
+
+Библиотека функциональных утилит для экосистемы DXT UI. Содержит готовые решения для типовых задач веб-разработки: работа с HTTP-запросами, геолокация, работа с датами, кеширование данных и многое другое.
+
+## Что входит в пакет
+
+### Классы (20+)
+
+- **Api** — выполнение HTTP-запросов с поддержкой кеширования, загрузочных индикаторов и эмуляции ответов
+- **Geo** — определение страны и языка пользователя, работа с геоданными и часовыми поясами
+- **Datetime** — работа с датами: форматирование, манипуляции, сравнение с учётом локализации
+- **Cache** — система кеширования данных с автоматической инвалидацией
+- **GeoFlag** — доступ к флагам стран (200+) с локализованными названиями
+- **GeoPhone** — телефонные коды и маски форматирования для всех стран
+- **GeoIntl** — интернационализация: форматирование чисел, валют, дат по региональным стандартам
+- **Cookie** — удобная работа с cookies
+- **Hash** — управление параметрами в URL hash
+- **DataStorage** — типизированная работа с localStorage и sessionStorage
+- **Loading** — глобальное управление индикаторами загрузки
+- **Translate** — система переводов с поддержкой подстановок
+- **Icons** — управление иконками и SVG-спрайтами
+
+### Композаблы для Vue 3 (10+)
+
+Реактивные обёртки над классами для использования в Vue-компонентах:
+
+- **useApiRef** — реактивные HTTP-запросы с автоматическим управлением состоянием загрузки
+- **useGeoIntlRef** — реактивное форматирование с учётом локали пользователя
+- **useStorageRef** — двусторонняя синхронизация ref с localStorage/sessionStorage
+- **useHashRef** — двусторонняя синхронизация ref с URL hash
+- **useCookieRef** — реактивная работа с cookies
+- **useLoadingRef** — реактивное отслеживание состояния загрузки
+- **useTranslateRef** — реактивная система переводов
+
+### Функции-помощники (100+)
+
+**Работа с массивами:** преобразование в массив, фильтрация, итерация, заполнение, уникальные значения
+
+**Работа с объектами:** глубокое копирование, слияние объектов, получение значений по пути, сравнение
+
+**Работа со строками:** преобразование регистра (camelCase, kebabCase), заполнение строк, применение шаблонов
+
+**Валидация:** проверка типов данных, проверка на заполненность, сравнение значений
+
+**DOM-утилиты:** поиск элементов, создание элементов, работа с атрибутами, прокрутка
+
+**Математика:** безопасное преобразование в числа, проценты, случайные числа, пошаговые значения
+
+**Асинхронность:** безопасное выполнение промисов и функций, работа с фреймами анимации
+
+**Буфер обмена:** копирование и чтение данных из буфера

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

@@ -13,7 +13,7 @@ import {Meta} from '@storybook/addon-docs/blocks'
 - **Автоматическая сериализация** — JSON сериализация/десериализация обрабатывается автоматически
 - **Валидация времени кеша** — опциональное истечение кеша с автоматической очисткой
 - **Singleton паттерн** — переиспользует экземпляры для одинаковых ключей хранения
-- **Управление префиксами** — настраиваемый префикс для всех ключей хранения
+- **Управление префиксами** — настраиваемый префикс для всех ключей хранения (по умолчанию 'ui-storage')
 - **Поддержка функций как значений** — принимает функции как значения для динамической генерации данных
 - **Совместимость с браузерами** — безопасное использование с серверным рендерингом
 
@@ -26,6 +26,8 @@ import {Meta} from '@storybook/addon-docs/blocks'
 **Параметры:**
 - `newPrefix: string` — новый префикс для ключей хранения
 
+**Возвращает:** `void`
+
 ```javascript
 import { DataStorage } from '@dxtmisha/functional'
 
@@ -33,7 +35,8 @@ import { DataStorage } from '@dxtmisha/functional'
 DataStorage.setPrefix('myapp-storage')
 
 // Все ключи хранения теперь будут использовать этот префикс:
-// 'user-settings' → 'myapp-storage-user-settings'
+// 'user-settings' → 'myapp-storage__user-settings'
+// По умолчанию префикс: 'ui-storage'
 ```
 
 ## Конструктор
@@ -46,6 +49,8 @@ DataStorage.setPrefix('myapp-storage')
 - `name: string` — имя ключа хранения
 - `isSession?: boolean` — использовать sessionStorage вместо localStorage (по умолчанию: false)
 
+**Возвращает:** `DataStorage<T>` — экземпляр класса (или существующий из кеша)
+
 ```javascript
 // Экземпляр localStorage
 const userPrefs = new DataStorage('user-preferences')
@@ -66,7 +71,7 @@ console.log(userPrefs === sameInstance) // true
 
 **Параметры:**
 - `defaultValue?: T | (() => T)` — значение по умолчанию или функция, если данные не найдены (опционально)
-- `cache?: number` — время кеширования в секундах для валидации (опционально)
+- `cache?: number` — время кеширования в **секундах** для валидации (опционально)
 
 **Возвращает:** `T | undefined` — сохранённые данные, значение по умолчанию или undefined
 
@@ -88,8 +93,10 @@ const config = settings.get(() => ({
   created: Date.now()
 }))
 
-// Получить с валидацией кеша (10 минут)
-const cachedData = settings.get(null, 600) // Возвращает null если данные старше 10 минут
+// Получить с валидацией кеша (600 секунд = 10 минут)
+const cachedData = settings.get(null, 600)
+// Возвращает undefined если данные старше 10 минут
+// Если кеш валиден - возвращает сохранённые данные
 ```
 
 ### `set`
@@ -131,108 +138,79 @@ const userStorage = new DataStorage('user-data')
 userStorage.set({ name: 'Иван', preferences: { theme: 'dark' } })
 console.log(userStorage.get()) // { name: 'Иван', preferences: { theme: 'dark' } }
 
-// Простое удаление
+// Удаление
 userStorage.remove()
 console.log(userStorage.get()) // undefined
 
-// Цепочка вызовов с другими экземплярами DataStorage
-const tempStorage = new DataStorage('temp-data')
-const anotherStorage = new DataStorage('another-data')
+// Цепочка вызовов
+userStorage
+  .set({ temp: 'data' })
+  .remove() // Удаляет только что сохранённые данные
+```
 
-// Операции цепочки через разные экземпляры
-tempStorage.set({ temp: true })
-anotherStorage.set({ another: true })
+### `update`
 
-tempStorage.remove() // Удалить временные данные
-anotherStorage.remove() // Удалить другие данные
+Обновляет данные из хранилища, перечитывая их заново.
 
-console.log(tempStorage.get()) // undefined
-console.log(anotherStorage.get()) // undefined
-```
+**Возвращает:** `this` — экземпляр DataStorage для цепочки вызовов
 
-## Практические примеры
+```javascript
+const storage = new DataStorage('shared-data')
 
-### Настройки пользователя
+// Установить данные
+storage.set({ value: 'initial' })
+console.log(storage.get()) // { value: 'initial' }
 
-```javascript
-class UserSettings {
-  constructor() {
-    this.storage = new DataStorage('user-settings')
-  }
-
-  getTheme() {
-    return this.storage.get('theme', 'light')
-  }
-
-  setTheme(theme) {
-    this.storage.set('theme', theme)
-  }
-
-  getLanguage() {
-    return this.storage.get('language', 'ru')
-  }
-
-  setLanguage(language) {
-    this.storage.set('language', language)
-  }
-
-  exportSettings() {
-    return {
-      theme: this.getTheme(),
-      language: this.getLanguage(),
-      notifications: this.storage.get('notifications', true)
-    }
-  }
-}
+// Данные изменились в другой вкладке/окне браузера
+// или напрямую через localStorage.setItem()
 
-// Использование
-const settings = new UserSettings()
-settings.setTheme('dark')
-console.log('Настройки:', settings.exportSettings())
+// Обновить данные из хранилища
+storage.update()
+console.log(storage.get()) // Получит актуальные данные из хранилища
+
+// Цепочка вызовов
+storage.update().get() // Обновить и получить свежие данные
 ```
 
-### Кеш данных приложения
+## Практические примеры
+
+### Настройки пользователя
 
 ```javascript
-const appCache = new DataStorage('app-cache', 'sessionStorage')
+const settings = new DataStorage('user-settings')
 
-function cacheApiData(endpoint, data) {
-  const key = `api_${endpoint.replace(/\//g, '_')}`
-  appCache.set(key, { data, timestamp: Date.now() }, 5 * 60 * 1000) // 5 минут
-}
+// Получить с значением по умолчанию
+const theme = settings.get(() => 'light')
+console.log(theme) // 'light' или сохранённое значение
 
-function getCachedData(endpoint) {
-  const key = `api_${endpoint.replace(/\//g, '_')}`
-  return appCache.get(key)
-}
+// Сохранить новое значение
+settings.set('dark')
 
-// Использование
-cacheApiData('/users', [{ id: 1, name: 'Иван' }])
-const cached = getCachedData('/users')
-console.log('Кешированные данные:', cached)
+// Удалить настройки
+settings.remove()
 ```
 
-### Состояние формы
+### Кеш данных с TTL
 
 ```javascript
-const formStorage = new DataStorage('form-draft')
+async function fetchWithCache(url, cacheDuration = 300) {
+  const storage = new DataStorage(`api_${url}`)
 
-function saveFormDraft(formData) {
-  formStorage.set('draft', formData)
-}
+  // Попытка получить из кеша (cacheDuration в секундах)
+  const cached = storage.get(undefined, cacheDuration)
+  if (cached) return cached
 
-function loadFormDraft() {
-  return formStorage.get('draft', {})
-}
+  // Загрузка свежих данных
+  const response = await fetch(url)
+  const data = await response.json()
 
-function clearFormDraft() {
-  formStorage.remove('draft')
+  // Сохранение в кеш
+  storage.set(data)
+  return data
 }
 
 // Использование
-saveFormDraft({ name: 'Иван', email: 'ivan@example.com' })
-const draft = loadFormDraft()
-console.log('Черновик формы:', draft)
+const users = await fetchWithCache('/api/users', 600) // Кеш на 10 минут
 ```
 
-Класс DataStorage предоставляет единый интерфейс для работы с браузерными хранилищами, обеспечивая типобезопасность, автоматическую сериализацию и гибкое управление TTL.
+Класс DataStorage предоставляет единый интерфейс для работы с браузерными хранилищами, обеспечивая типобезопасность, автоматическую сериализацию и гибкое управление временем жизни данных с поддержкой singleton паттерна для эффективного использования памяти.