@dxtmisha/wiki 0.24.2 → 0.25.1

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

@@ -0,0 +1,305 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/functional/ru/Classes/BroadcastMessage'/>
+
+# Класс BroadcastMessage
+
+Класс для работы с сообщениями BroadcastChannel между вкладками/окнами браузера. Обеспечивает коммуникацию в реальном времени между различными контекстами одного источника с автоматическим именованием каналов и обработкой сообщений.
+
+## Основные возможности
+
+- **Межвкладочная коммуникация** — отправка и получение сообщений между вкладками и окнами браузера
+- **Автоматическое именование каналов** — уникальные имена каналов для каждого экземпляра браузера, сохраняемые в localStorage
+- **Типобезопасная передача сообщений** — полная поддержка TypeScript с генерик-типами сообщений
+- **Обработка через callback** — гибкая обработка сообщений через callback-функции
+- **Обработка ошибок** — корректная обработка ошибок с логированием в консоль
+- **Безопасность SSR** — автоматическое определение окружения DOM runtime
+
+## Основное использование
+
+### Конструктор
+
+Создаёт новый экземпляр BroadcastMessage с указанным именем канала и опциональным callback.
+
+**Параметры:**
+- `name: string` — идентификатор имени канала
+- `callback?: (event: MessageEvent<Message>) => void` — опциональный callback для получаемых сообщений
+
+```javascript
+import { BroadcastMessage } from '@dxtmisha/functional'
+
+// Создание канала с callback
+const channel = new BroadcastMessage('user-updates', (event) => {
+  console.log('Получено сообщение:', event.data)
+})
+
+// Создание канала без callback (можно установить позже)
+const notifications = new BroadcastMessage('notifications')
+```
+
+### `post`
+
+Отправляет сообщение всем подключённым вкладкам/окнам на том же канале.
+
+**Параметры:**
+- `message: Message` — сообщение для отправки
+
+**Возвращает:** `this` — для цепочки вызовов
+
+```javascript
+import { BroadcastMessage } from '@dxtmisha/functional'
+
+const userChannel = new BroadcastMessage('user-updates')
+
+// Отправка простого сообщения
+userChannel.post({ type: 'login', userId: 123 })
+
+// Цепочка вызовов
+userChannel
+  .post({ type: 'status', value: 'online' })
+  .post({ type: 'activity', timestamp: Date.now() })
+```
+
+### `setCallback`
+
+Устанавливает или обновляет callback-функцию для обработки получаемых сообщений.
+
+**Параметры:**
+- `callback: (event: MessageEvent<Message>) => void` — callback-функция
+
+**Возвращает:** `this` — для цепочки вызовов
+
+```javascript
+import { BroadcastMessage } from '@dxtmisha/functional'
+
+const channel = new BroadcastMessage('app-events')
+
+// Установка callback позже
+channel.setCallback((event) => {
+  console.log('Получено событие:', event.data)
+})
+
+// Обновление callback
+channel.setCallback((event) => {
+  if (event.data.type === 'refresh') {
+    location.reload()
+  }
+})
+```
+
+## Расширенные примеры
+
+### Синхронизация состояния между вкладками
+
+```javascript
+import { BroadcastMessage } from '@dxtmisha/functional'
+import { ref } from 'vue'
+
+// Создание реактивного состояния
+const userStatus = ref('offline')
+
+// Создание канала broadcast
+const statusChannel = new BroadcastMessage('user-status', (event) => {
+  // Обновление локального состояния при изменениях из других вкладок
+  userStatus.value = event.data.status
+  console.log('Статус обновлён из другой вкладки:', event.data.status)
+})
+
+// Функция для обновления статуса и оповещения других вкладок
+function updateStatus(newStatus) {
+  userStatus.value = newStatus
+  statusChannel.post({ status: newStatus, timestamp: Date.now() })
+}
+
+// Использование
+updateStatus('online')  // Обновляет эту вкладку и уведомляет другие
+```
+
+### Корзина покупок в нескольких вкладках
+
+```javascript
+import { BroadcastMessage } from '@dxtmisha/functional'
+
+// Определение типов сообщений
+interface CartMessage {
+  action: 'add' | 'remove' | 'clear'
+  productId?: number
+  quantity?: number
+}
+
+// Создание канала с типизированными сообщениями
+const cartChannel = new BroadcastMessage<CartMessage>('shopping-cart')
+
+// Настройка обработчика сообщений
+cartChannel.setCallback((event) => {
+  const { action, productId, quantity } = event.data
+
+  switch (action) {
+    case 'add':
+      console.log(`Добавление ${quantity} товара ${productId}`)
+      addToCart(productId, quantity)
+      break
+    case 'remove':
+      console.log(`Удаление товара ${productId}`)
+      removeFromCart(productId)
+      break
+    case 'clear':
+      console.log('Очистка корзины')
+      clearCart()
+      break
+  }
+})
+
+// Трансляция обновлений корзины
+function addProduct(productId, quantity) {
+  addToCart(productId, quantity)
+  cartChannel.post({ action: 'add', productId, quantity })
+}
+```
+
+### Синхронизация состояния аутентификации
+
+```javascript
+import { BroadcastMessage } from '@dxtmisha/functional'
+
+interface AuthMessage {
+  type: 'login' | 'logout' | 'token-refresh'
+  userId?: number
+  token?: string
+}
+
+const authChannel = new BroadcastMessage<AuthMessage>('auth-events', (event) => {
+  switch (event.data.type) {
+    case 'login':
+      console.log('Пользователь вошёл:', event.data.userId)
+      location.reload()
+      break
+
+    case 'logout':
+      console.log('Пользователь вышел, перенаправление...')
+      localStorage.removeItem('auth-token')
+      window.location.href = '/login'
+      break
+
+    case 'token-refresh':
+      console.log('Токен обновлён')
+      localStorage.setItem('auth-token', event.data.token)
+      break
+  }
+})
+
+// Трансляция входа
+function handleLogin(userId, token) {
+  localStorage.setItem('auth-token', token)
+  authChannel.post({ type: 'login', userId, token })
+}
+
+// Трансляция выхода
+function handleLogout() {
+  localStorage.removeItem('auth-token')
+  authChannel.post({ type: 'logout' })
+}
+```
+
+### Уведомления в реальном времени
+
+```javascript
+import { BroadcastMessage } from '@dxtmisha/functional'
+
+interface Notification {
+  id: string
+  title: string
+  message: string
+  type: 'info' | 'warning' | 'error' | 'success'
+  timestamp: number
+}
+
+const notificationChannel = new BroadcastMessage<Notification>('notifications')
+
+// Настройка обработчика уведомлений
+notificationChannel.setCallback((event) => {
+  const notification = event.data
+
+  showNotification(notification.title, notification.message, notification.type)
+
+  if (notification.type === 'error') {
+    playErrorSound()
+  }
+})
+
+// Отправка уведомления всем вкладкам
+function broadcastNotification(title, message, type = 'info') {
+  const notification = {
+    id: crypto.randomUUID(),
+    title,
+    message,
+    type,
+    timestamp: Date.now()
+  }
+
+  notificationChannel.post(notification)
+}
+
+// Использование
+broadcastNotification('Новое сообщение', 'У вас новое сообщение от Ивана', 'info')
+```
+
+## Детали реализации
+
+### Уникальное именование каналов
+
+Каждый экземпляр браузера генерирует уникальный идентификатор, сохраняемый в localStorage (`__broadcast-name`). Это гарантирует изоляцию каналов между различными экземплярами браузера, при этом позволяя коммуникацию внутри одного экземпляра между вкладками.
+
+```javascript
+// Формат имени канала: name_{случайные_7_цифр}__ваше-имя-канала
+// Пример: name_1234567__user-updates
+```
+
+### Обработка ошибок
+
+BroadcastMessage корректно обрабатывает ошибки и логирует их в консоль:
+
+```javascript
+const channel = new BroadcastMessage('my-channel')
+// Если BroadcastChannel не поддерживается или инициализация не удалась,
+// ошибка логируется: "BroadcastMessage my-channel: [детали ошибки]"
+```
+
+### Совместимость с SSR
+
+Класс автоматически определяет окружение DOM runtime с помощью `isDomRuntime()`, что делает его безопасным для использования в контекстах SSR/SSG, где BroadcastChannel API недоступен.
+
+## Типобезопасность
+
+```typescript
+import { BroadcastMessage } from '@dxtmisha/functional'
+
+// Определение структуры сообщения
+interface UserUpdate {
+  userId: number
+  action: 'online' | 'offline' | 'typing'
+  timestamp: number
+}
+
+// Создание типизированного канала
+const channel = new BroadcastMessage<UserUpdate>('users')
+
+// TypeScript обеспечивает типобезопасность
+channel.post({
+  userId: 123,
+  action: 'online',
+  timestamp: Date.now()
+}) // ✓ Валидно
+
+channel.post({ invalid: 'data' }) // ✗ Ошибка TypeScript
+```
+
+## Совместимость с браузерами
+
+BroadcastChannel API поддерживается в:
+- Chrome/Edge 54+
+- Firefox 38+
+- Safari 15.4+
+- Opera 41+
+
+Для старых браузеров рассмотрите использование полифилла или механизма запасного варианта.

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

@@ -45,6 +45,42 @@ applyTemplate('Это [bold]жирный текст[/bold]', { bold: '<b>[conten
 applyTemplate('Text with [red]colored[/red] word', { red: '<span style="color:red">[content]</span>' })
 ```
 
+## `blobToBase64`
+
+Преобразует Blob в строку Base64 (data URL).
+
+**Параметры:**
+- `blob: Blob` — Blob объект для преобразования
+
+```javascript
+import { blobToBase64 } from '@dxtmisha/functional'
+
+const blob = new Blob(['Hello World'], { type: 'text/plain' })
+const base64 = await blobToBase64(blob)
+// 'data:text/plain;base64,SGVsbG8gV29ybGQ='
+
+// Использование с изображением
+const imageBlob = new Blob([imageData], { type: 'image/png' })
+const imageBase64 = await blobToBase64(imageBlob)
+// 'data:image/png;base64,iVBORw0KGgo...'
+```
+
+
+## `encodeAttribute`
+
+Кодирует специальные символы в строке для безопасного использования в HTML-атрибутах. Преобразует символы `&`, `<`, `>`, `"`, `'` в соответствующие HTML-сущности для предотвращения XSS-атак и корректного отображения.
+
+**Параметры:**
+- `text: string` — текст для кодирования
+
+```javascript
+import { encodeAttribute } from '@dxtmisha/functional'
+
+encodeAttribute('Hello & "World"') // 'Hello &amp; &quot;World&quot;'
+encodeAttribute('<script>alert("XSS")</script>') // '&lt;script&gt;alert(&quot;XSS&quot;)&lt;/script&gt;'
+encodeAttribute("It's a test") // 'It&#39;s a test'
+```
+
 ## `replaceRecursive`
 
 Рекурсивно заменяет значения в объекте или массиве.
@@ -78,6 +114,37 @@ replaceTemplate('User [id]: [name]', {id: '123', name: 'John'}) // 'User 123: Jo
 replaceTemplate('Time: [time]', {time: () => new Date().toLocaleString()}) // с функцией
 ```
 
+## `resizeImageByMax`
+
+Изменяет размер изображения, чтобы оно соответствовало ограничению максимального размера.
+
+**Параметры:**
+- `image: HTMLImageElement | string` — элемент изображения или URL
+- `maxSize: number` — максимальный размер ширины или высоты
+- `type: 'auto' | 'width' | 'height'` — тип изменения размера (по умолчанию 'auto')
+- `typeData?: string` — тип данных результирующего изображения (например, 'image/png', 'image/jpeg')
+
+```javascript
+import { resizeImageByMax } from '@dxtmisha/functional'
+
+// Автоматическое масштабирование (по большей стороне)
+const image = document.querySelector('img')
+const resized = resizeImageByMax(image, 800) // data URL
+// Изображение 1200x800 станет 800x533
+
+// Масштабирование по ширине
+resizeImageByMax(image, 600, 'width')
+// Ширина будет 600px, высота пропорциональна
+
+// Масштабирование по высоте
+resizeImageByMax(image, 400, 'height')
+// Высота будет 400px, ширина пропорциональна
+
+// С указанием типа данных
+resizeImageByMax(image, 1024, 'auto', 'image/jpeg')
+// Возвращает JPEG data URL
+```
+
 ## `secondToTime`
 
 Преобразует секунды в формат времени (часы:минуты:секунды).

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

@@ -37,6 +37,31 @@ const copy = copyObject(original)
 copy.data.age = 25 // original.data.age остается 30
 ```
 
+## `copyObjectLite`
+
+Создает поверхностную копию простого объекта. Если передан параметр `source`, создаёт новый объект и объединяет `value` и `source`.
+
+**Параметры:**
+- `value: T` — объект для копирования
+- `source?: any` — дополнительные свойства для копирования (опционально)
+
+```javascript
+import { copyObjectLite } from '@dxtmisha/functional'
+
+const original = { name: 'John', age: 30 }
+const copy = copyObjectLite(original) // { name: 'John', age: 30 }
+
+// С дополнительными свойствами
+const extended = copyObjectLite(original, { city: 'Moscow' })
+// { name: 'John', age: 30, city: 'Moscow' }
+
+// Переопределение свойств
+const overridden = copyObjectLite(original, { age: 25 })
+// { name: 'John', age: 25 }
+```
+
+**Примечание:** Это поверхностная копия — вложенные объекты сохраняют ссылки на исходные. Для глубокого клонирования используйте `copyObject`, `structuredClone` или `_.cloneDeep`.
+
 ## `forEach`
 
 Универсальная функция итерации для массивов, объектов и Map.

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

@@ -68,7 +68,7 @@ const staticDatetime = new DatetimeRef('2024-01-15', 'date', 'ru-RU')
 
 ```javascript
 const yearValue = datetime.getYear()
-// Автоматически обновляется при изменении д��ты
+// Автоматически обновляется при изменении даты
 ```
 
 ### `getMonth`
@@ -228,7 +228,7 @@ const withoutTz = datetime.standard(false)
 
 ### Vue компонент с реактивной датой
 
-```vue
+```html
 <template>
   <div>
     <span>{{ datetime.getYear() }}/{{ datetime.getMonth() + 1 }}/{{ datetime.getDay() }}</span>

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

@@ -259,7 +259,7 @@ const eventRef = new EventRef(buttonRef, containerRef, 'click')
 
 ### Vue компонент с реактивными событиями
 
-```vue
+```html
 <template>
   <button ref="buttonEl">Нажми меня</button>
   <input ref="inputEl" placeholder="Введите...">

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

@@ -6,6 +6,62 @@ import {Meta} from '@storybook/addon-docs/blocks'
 
 Набор функций для универсального выполнения синхронных и асинхронных операций.
 
+## `computedByLanguage`
+
+Создает реактивное вычисляемое свойство, значение которого зависит от текущего языка и заданных условий.
+
+**Параметры:**
+- `getter: ComputedGetter<R>` — функция, возвращающая основное значение в зависимости от языка
+- `getterNone: R | (() => R)` — альтернативное значение, если условия не выполнены или getter вернул undefined (по умолчанию undefined)
+- `conditions: () => boolean` — условие для вызова основного getter (опционально)
+- `debugOptions: DebuggerOptions` — опции отладки Vue (опционально)
+
+```javascript
+import { computedByLanguage } from '@dxtmisha/functional'
+import { ref } from 'vue'
+
+// Простой пример с переводами
+const title = computedByLanguage(
+  () => {
+    const lang = GeoRef.get().value
+    return lang === 'ru' ? 'Заголовок' : 'Title'
+  },
+  'Default Title'
+)
+
+// С условием
+const description = computedByLanguage(
+  () => {
+    const lang = GeoRef.get().value
+    const translations = {
+      ru: 'Описание на русском',
+      en: 'Description in English'
+    }
+    return translations[lang]
+  },
+  () => 'Описание по умолчанию',
+  () => showDescription.value // условие показа
+)
+
+// Использование в компоненте
+export default {
+  setup() {
+    const showText = ref(true)
+
+    const greeting = computedByLanguage(
+      () => {
+        const lang = GeoRef.get().value
+        return lang === 'ru' ? 'Привет, мир!' : 'Hello, world!'
+      },
+      'Greeting',
+      () => showText.value
+    )
+
+    return { greeting }
+  }
+}
+```
+
 ## `executeFunction`
 
 Выполняет функцию и возвращает её результат, или возвращает входные данные, если это не функция.
@@ -148,3 +204,5 @@ export default {
   }
 }
 ```
+
+

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

@@ -162,7 +162,7 @@ countryCode.value = 'en-US'
 
 ### Vue компонент с флагами стран
 
-```vue
+```html
 <template>
   <div class="country-selector">
     <div class="current-country">

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

@@ -69,7 +69,7 @@ intl.getLocation() // 'ru-RU'
 
 Возвращает первый день недели для текущей локали.
 
-**Возвращает:** `string` — код первого дня ('Su' для во��кресенья, 'Mo' для понедельника)
+**Возвращает:** `string` — код первого дня ('Su' для воскресенья, 'Mo' для понедельника)
 
 ```javascript
 const intl = new GeoIntl('ru-RU')
@@ -517,7 +517,7 @@ intl.relative(yesterday, { numeric: 'always' }) // '1 день назад'
 - `todayValue?: Date` — базовая дата для сравнения (опционально)
 - `relativeOptions?: string | Intl.RelativeTimeFormatOptions` — опции относительного времени (опционально)
 - `dateOptions?: string | Intl.DateTimeFormatOptions` — опции обычной даты (опционально)
-- `type?: GeoDate` — тип форматиро��ания даты (опционально)
+- `type?: GeoDate` — тип форматирования даты (опционально)
 - `hour24?: boolean` — использовать 24-часовой формат (опционально)
 
 **Возвращает:** `string` — отформатированное относительное время или дата

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

@@ -291,7 +291,7 @@ const daysList = intl.weekdays('long')
 
 ### Vue компонент с локализацией
 
-```vue
+```html
 <template>
   <div class="localized-content">
     <h2>{{ intl.countryName('RU') }}</h2>

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

@@ -141,7 +141,7 @@ const flag = new GeoFlagRef() // будет использовать de-DE
 
 ### Vue компонент с глобальной геолокацией
 
-```vue
+```html
 <template>
   <div class="geo-info">
     <h2>Текущая локация</h2>
@@ -202,7 +202,7 @@ GeoRef.set(userLocale)
 
 ### Глобальный провайдер локали
 
-```vue
+```html
 <!-- App.vue -->
 <template>
   <div class="app">

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

@@ -534,4 +534,4 @@ function createListFromInput<T extends ListDataBasic>(
 }
 ```
 
-Эти типы списков обеспечивают полную типизацию для создан��я интерактивных списков, меню, навигации и других компонентов с поддержкой выбора, поиска и группировки элементов.
+Эти типы списков обеспечивают полную типизацию для создания интерактивных списков, меню, навигации и других компонентов с поддержкой выбора, поиска и группировки элементов.