@dxtmisha/wiki 0.24.0 → 0.24.1

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

@@ -0,0 +1,344 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/functional/ru/Composables/useBroadcastValueRef'/>
+
+# Композабл useBroadcastValueRef
+
+Композабл для создания реактивной переменной, синхронизированной между вкладками браузера через Broadcast Channel API. Автоматически управляет передачей данных между открытыми вкладками одного домена в реальном времени без использования localStorage. Идеально подходит для синхронизации состояния приложения, уведомлений и обмена данными между вкладками.
+
+## Основные возможности
+
+- **Реальная синхронизация** — мгновенная передача данных между вкладками браузера
+- **Broadcast Channel API** — использует нативный браузерный API для эффективной коммуникации
+- **Автоматическая синхронизация** — изменения в одной вкладке автоматически отражаются во всех остальных
+- **Singleton паттерн** — переиспользование канала для одинаковых имён
+- **Уникальная идентификация** — каждая сессия браузера получает уникальный ID
+- **Типобезопасность** — полная поддержка TypeScript с дженериками
+- **Значения по умолчанию** — поддержка начальных значений и функций-фабрик
+- **Изоляция сессий** — данные не передаются между разными сессиями браузера
+
+## Функция
+
+### `useBroadcastValueRef`
+
+Создаёт реактивную переменную, синхронизированную между вкладками через Broadcast Channel.
+
+**Параметры:**
+- `name: string` — имя канала для связи между вкладками
+- `defaultValue?: T | string | (() => (T | string))` — значение по умолчанию или функция для его генерации (опционально)
+
+**Возвращает:** `Ref<T | string | undefined>` — реактивная переменная Vue, синхронизированная между вкладками
+
+```javascript
+import { useBroadcastValueRef } from '@dxtmisha/functional'
+
+// Простое использование
+const sharedCounter = useBroadcastValueRef('counter')
+
+// С значением по умолчанию
+const activeTab = useBroadcastValueRef('active-tab', 'home')
+
+// С функцией по умолчанию
+const sessionId = useBroadcastValueRef('session', () => Math.random().toString(36))
+```
+
+## Основное использование
+
+### Базовая синхронизация
+
+```javascript
+import { useBroadcastValueRef } from '@dxtmisha/functional'
+
+// Создание синхронизированной переменной
+const counter = useBroadcastValueRef('counter', 0)
+
+// В первой вкладке
+counter.value = 5
+
+// Во второй вкладке автоматически обновляется
+console.log(counter.value) // 5
+
+// Изменение в любой вкладке отражается во всех остальных
+counter.value = 10
+// Все вкладки получат counter.value === 10 мгновенно
+```
+
+### Singleton паттерн
+
+```javascript
+// При повторном вызове с тем же именем возвращается существующий канал
+const channel1 = useBroadcastValueRef('notifications', null)
+const channel2 = useBroadcastValueRef('notifications', null)
+
+console.log(channel1 === channel2) // true - тот же ref
+
+channel1.value = { type: 'info', message: 'Привет!' }
+console.log(channel2.value) // { type: 'info', message: 'Привет!' }
+```
+
+## Использование в компонентах
+
+### Синхронизация уведомлений
+
+```javascript
+import { useBroadcastValueRef } from '@dxtmisha/functional'
+
+export default {
+  setup() {
+    const notification = useBroadcastValueRef('notification', null)
+
+    const showNotification = (message, type = 'info') => {
+      notification.value = {
+        id: Date.now(),
+        type,
+        message,
+        timestamp: new Date()
+      }
+    }
+
+    return {
+      notification,
+      showNotification
+    }
+  }
+}
+
+// Template:
+// <div v-if="notification" class="notification">
+//   <span>{{ notification.message }}</span>
+//   <button @click="notification = null">×</button>
+// </div>
+//
+// Уведомление показывается во всех открытых вкладках
+```
+
+### Общий счётчик
+
+```javascript
+import { useBroadcastValueRef } from '@dxtmisha/functional'
+
+export default {
+  setup() {
+    const cartCount = useBroadcastValueRef('cart-count', 0)
+
+    const addToCart = () => {
+      cartCount.value = (cartCount.value || 0) + 1
+    }
+
+    const removeFromCart = () => {
+      if (cartCount.value > 0) {
+        cartCount.value--
+      }
+    }
+
+    return {
+      cartCount,
+      addToCart,
+      removeFromCart
+    }
+  }
+}
+
+// Template:
+// <div>
+//   <span class="badge">{{ cartCount }}</span>
+//   <button @click="addToCart">Добавить</button>
+//   <button @click="removeFromCart">Удалить</button>
+// </div>
+//
+// Счётчик синхронизируется между всеми вкладками
+```
+
+## Синхронизация состояния
+
+### Активная вкладка
+
+```javascript
+import { useBroadcastValueRef } from '@dxtmisha/functional'
+import { watch } from 'vue'
+
+export default {
+  setup() {
+    const activeTab = useBroadcastValueRef('active-nav-tab', 'home')
+
+    const setActiveTab = (tab) => {
+      activeTab.value = tab
+    }
+
+    // Отслеживание изменений из других вкладок
+    watch(activeTab, (newTab) => {
+      console.log(`Активная вкладка изменена на: ${newTab}`)
+    })
+
+    return {
+      activeTab,
+      setActiveTab
+    }
+  }
+}
+
+// При переключении вкладки в одном окне,
+// все остальные окна синхронизируются
+```
+
+### Статус авторизации
+
+```javascript
+import { useBroadcastValueRef } from '@dxtmisha/functional'
+
+export default {
+  setup() {
+    const isAuthenticated = useBroadcastValueRef('auth-status', false)
+    const currentUser = useBroadcastValueRef('current-user', null)
+
+    const login = (userData) => {
+      currentUser.value = userData
+      isAuthenticated.value = true
+    }
+
+    const logout = () => {
+      currentUser.value = null
+      isAuthenticated.value = false
+    }
+
+    return {
+      isAuthenticated,
+      currentUser,
+      login,
+      logout
+    }
+  }
+}
+
+// При входе/выходе в одной вкладке,
+// все остальные вкладки обновляются мгновенно
+```
+
+## Отличия от useStorageRef
+
+```javascript
+// useStorageRef - через localStorage (постоянное хранение)
+const persistentData = useStorageRef('theme', 'light')
+// - Данные сохраняются в localStorage
+// - Синхронизация через storage event
+// - Более медленная передача данных
+// - Данные остаются после закрытия браузера
+
+// useBroadcastValueRef - через Broadcast Channel (в памяти)
+const realtimeData = useBroadcastValueRef('active-users', [])
+// - Данные в памяти (не сохраняются)
+// - Мгновенная синхронизация
+// - Быстрая передача данных
+// - Данные теряются при закрытии всех вкладок
+// - Изоляция между сессиями браузера
+```
+
+## Работа с типами данных
+
+```javascript
+// Числа
+const counter = useBroadcastValueRef<number>('counter', 0)
+counter.value = 42
+
+// Строки
+const message = useBroadcastValueRef<string>('message', '')
+message.value = 'Привет из другой вкладки!'
+
+// Объекты
+const userState = useBroadcastValueRef('user-state', {
+  id: null,
+  name: '',
+  online: false
+})
+userState.value = { id: 1, name: 'Иван', online: true }
+
+// Массивы
+const activeUsers = useBroadcastValueRef<number[]>('active-users', [])
+activeUsers.value = [1, 2, 3, 4, 5]
+```
+
+## Примеры использования
+
+### Чат между вкладками
+
+```javascript
+const chatMessages = useBroadcastValueRef('chat-messages', [])
+
+const sendMessage = (text) => {
+  const message = {
+    id: Date.now(),
+    text,
+    timestamp: new Date()
+  }
+
+  chatMessages.value = [...(chatMessages.value || []), message]
+}
+
+// Сообщения появляются во всех открытых вкладках мгновенно
+```
+
+### Синхронизация воспроизведения
+
+```javascript
+const playerState = useBroadcastValueRef('player', {
+  isPlaying: false,
+  currentTime: 0,
+  track: null
+})
+
+const play = () => {
+  playerState.value = { ...playerState.value, isPlaying: true }
+}
+
+const pause = () => {
+  playerState.value = { ...playerState.value, isPlaying: false }
+}
+
+// Управление плеером в одной вкладке
+// влияет на плееры во всех остальных
+```
+
+### Общие фильтры
+
+```javascript
+const filters = useBroadcastValueRef('search-filters', {
+  category: 'all',
+  priceMin: 0,
+  priceMax: 10000
+})
+
+const updateFilter = (key, value) => {
+  filters.value = { ...filters.value, [key]: value }
+}
+
+// Изменение фильтров синхронизируется
+// между всеми открытыми страницами поиска
+```
+
+## Уникальная идентификация сессии
+
+Композабл автоматически создаёт уникальный ID для каждой сессии браузера и сохраняет его в localStorage:
+
+```javascript
+// При первом запуске генерируется случайный ID
+// broadcast__name_1234567__counter
+//            ^^^^^^^^^ - уникальный ID сессии
+
+// Этот ID переиспользуется для всех каналов в рамках одной сессии
+// Разные сессии браузера имеют разные ID и не пересекаются
+```
+
+## Особенности Broadcast Channel API
+
+```javascript
+// Broadcast Channel работает только:
+// - В рамках одного origin (протокол + домен + порт)
+// - Между вкладками одного браузера
+// - В той же сессии браузера
+
+// НЕ работает:
+// - Между разными браузерами
+// - Между разными доменами
+// - В режиме инкогнито между обычными вкладками
+```
+

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

@@ -0,0 +1,348 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/functional/ru/Composables/useCookieRef'/>
+
+# Композабл useCookieRef
+
+Композабл для создания реактивной переменной, синхронизированной с cookies браузера. Автоматически управляет чтением и записью значений в cookies с поддержкой синхронизации между вкладками через Broadcast Channel API, настройками срока действия и singleton паттерна для эффективного переиспользования.
+
+## Основные возможности
+
+- **Двусторонняя синхронизация** — автоматическая синхронизация между ref и cookies
+- **Синхронизация между вкладками** — изменения в одной вкладке мгновенно отражаются во всех остальных через Broadcast Channel
+- **Автоматическое сохранение** — изменения ref автоматически сохраняются в cookies
+- **Настройка срока действия** — поддержка expires, max-age и других опций cookies
+- **Singleton паттерн** — переиспользование ref для одинаковых имён cookies
+- **Типобезопасность** — полная поддержка TypeScript с дженериками
+- **Значения по умолчанию** — поддержка начальных значений и функций-фабрик
+- **Интеграция с Cookie** — использует класс Cookie для управления cookies
+
+## Функция
+
+### `useCookieRef`
+
+Создаёт реактивную переменную, синхронизированную с cookies браузера.
+
+**Параметры:**
+- `name: string` — имя cookie
+- `defaultValue?: T | string | (() => (T | string))` — значение по умолчанию или функция для его генерации (опционально)
+- `options?: CookieOptions` — дополнительные параметры cookie (опционально)
+
+**Возвращает:** `Ref<T | string | undefined>` — реактивная переменная Vue, связанная с cookie
+
+**CookieOptions:**
+- `expires?: number | Date` — дата истечения срока действия
+- `path?: string` — путь для cookie (по умолчанию '/')
+- `domain?: string` — домен для cookie
+- `secure?: boolean` — использовать только HTTPS
+- `sameSite?: 'Strict' | 'Lax' | 'None'` — политика SameSite
+
+```javascript
+import { useCookieRef } from '@dxtmisha/functional'
+
+// Простое использование
+const userToken = useCookieRef('token')
+
+// С значением по умолчанию
+const theme = useCookieRef('theme', 'light')
+
+// С опциями (срок действия 7 дней)
+const rememberMe = useCookieRef('remember', true, {
+  expires: 7,
+  path: '/',
+  sameSite: 'Lax'
+})
+```
+
+## Основное использование
+
+### Базовая синхронизация
+
+```javascript
+import { useCookieRef } from '@dxtmisha/functional'
+
+// Создание ref, синхронизированного с cookie
+const userTheme = useCookieRef('theme', 'light')
+
+// При изменении ref - cookie автоматически обновляется
+userTheme.value = 'dark'
+// document.cookie содержит: 'theme=dark'
+
+// При перезагрузке страницы значение восстанавливается
+console.log(userTheme.value) // 'dark'
+```
+
+### Singleton паттерн
+
+```javascript
+// При повторном вызове с тем же именем возвращается существующий ref
+const token1 = useCookieRef('auth-token', '')
+const token2 = useCookieRef('auth-token', '')
+
+console.log(token1 === token2) // true - тот же ref
+
+token1.value = 'abc123'
+console.log(token2.value) // 'abc123' - оба указывают на один ref
+```
+
+### Синхронизация между вкладками
+
+```javascript
+import { useCookieRef } from '@dxtmisha/functional'
+
+// В первой вкладке
+const userState = useCookieRef('user-online', 'active')
+userState.value = 'away'
+
+// Во второй вкладке автоматически обновляется мгновенно
+// userState.value === 'away' (благодаря Broadcast Channel)
+
+// В третьей вкладке
+const sameState = useCookieRef('user-online', 'active')
+console.log(sameState.value) // 'away'
+
+// Изменение в любой вкладке синхронизируется со всеми остальными
+```
+
+## Использование в компонентах
+
+### Настройки пользователя
+
+```javascript
+import { useCookieRef } from '@dxtmisha/functional'
+
+export default {
+  setup() {
+    const theme = useCookieRef('user-theme', 'light', {
+      expires: 365 // 1 год
+    })
+
+    const language = useCookieRef('user-language', 'ru', {
+      expires: 365
+    })
+
+    const fontSize = useCookieRef('font-size', 16, {
+      expires: 30 // 30 дней
+    })
+
+    return {
+      theme,
+      language,
+      fontSize
+    }
+  }
+}
+
+// Template:
+// <div>
+//   <select v-model="theme">
+//     <option value="light">Светлая</option>
+//     <option value="dark">Тёмная</option>
+//   </select>
+//   <select v-model="language">
+//     <option value="ru">Русский</option>
+//     <option value="en">English</option>
+//   </select>
+// </div>
+```
+
+### Авторизация с "Запомнить меня"
+
+```javascript
+import { useCookieRef } from '@dxtmisha/functional'
+
+export default {
+  setup() {
+    const authToken = useCookieRef('auth-token', '', {
+      expires: 7, // 7 дней
+      secure: true,
+      sameSite: 'Strict'
+    })
+
+    const rememberMe = useCookieRef('remember-me', false)
+
+    const login = (token) => {
+      const expires = rememberMe.value ? 30 : 1 // 30 дней или 1 день
+      authToken.value = token
+
+      // Обновить опции cookie
+      useCookieRef('auth-token', token, {
+        expires,
+        secure: true,
+        sameSite: 'Strict'
+      })
+    }
+
+    const logout = () => {
+      authToken.value = ''
+      rememberMe.value = false
+    }
+
+    return {
+      authToken,
+      rememberMe,
+      login,
+      logout
+    }
+  }
+}
+```
+
+## Настройки cookie
+
+### Срок действия
+
+```javascript
+// Expires в днях
+const token = useCookieRef('token', '', {
+  expires: 7 // удалится через 7 дней
+})
+
+// Expires как Date
+const session = useCookieRef('session', '', {
+  expires: new Date('2025-12-31')
+})
+
+// Без expires (сессионная cookie, удаляется при закрытии браузера)
+const tempData = useCookieRef('temp', '')
+```
+
+### Безопасность
+
+```javascript
+// HTTPS only
+const secureToken = useCookieRef('secure-token', '', {
+  secure: true,
+  sameSite: 'Strict'
+})
+
+// Cross-site запросы
+const apiToken = useCookieRef('api-token', '', {
+  secure: true,
+  sameSite: 'None' // требуется secure: true
+})
+```
+
+### Путь и домен
+
+```javascript
+// Для конкретного пути
+const adminPrefs = useCookieRef('admin-prefs', {}, {
+  path: '/admin'
+})
+
+// Для поддомена
+const sharedData = useCookieRef('shared', '', {
+  domain: '.example.com' // доступно для всех поддоменов
+})
+```
+
+## Работа с типами данных
+
+```javascript
+// Строки
+const username = useCookieRef<string>('username', '')
+username.value = 'Иван'
+
+// Числа (автоматическая сериализация)
+const count = useCookieRef<number>('count', 0)
+count.value = 42
+
+// Булевы значения
+const accepted = useCookieRef<boolean>('accepted', false)
+accepted.value = true
+
+// Объекты (JSON сериализация)
+const userPrefs = useCookieRef('prefs', {
+  theme: 'dark',
+  notifications: true
+})
+userPrefs.value = { theme: 'light', notifications: false }
+```
+
+## Интеграция с классом Cookie
+
+Композабл использует класс `Cookie` для управления cookies:
+
+```javascript
+import { Cookie } from '@dxtmisha/functional'
+
+// Прямое использование класса
+const cookie = new Cookie('theme')
+cookie.set('dark', { expires: 30 })
+console.log(cookie.get()) // 'dark'
+
+// useCookieRef автоматически синхронизируется
+const themeRef = useCookieRef('theme')
+console.log(themeRef.value) // 'dark'
+
+// Изменения через Cookie отражаются в ref (через Broadcast Channel)
+cookie.set('light')
+// themeRef.value автоматически обновится во всех вкладках
+```
+
+## Примеры использования
+
+### Согласие на cookies (GDPR)
+
+```javascript
+const cookieConsent = useCookieRef('cookie-consent', false, {
+  expires: 365,
+  sameSite: 'Lax'
+})
+
+const acceptCookies = () => {
+  cookieConsent.value = true
+}
+
+// В шаблоне:
+// <div v-if="!cookieConsent" class="cookie-banner">
+//   <p>Мы используем cookies...</p>
+//   <button @click="acceptCookies">Принять</button>
+// </div>
+```
+
+### Корзина покупок
+
+```javascript
+const cart = useCookieRef<CartItem[]>('shopping-cart', [], {
+  expires: 7
+})
+
+const addToCart = (item) => {
+  cart.value = [...cart.value, item]
+}
+
+const removeFromCart = (itemId) => {
+  cart.value = cart.value.filter(item => item.id !== itemId)
+}
+
+// Корзина синхронизируется между вкладками автоматически
+```
+
+### Отслеживание последних просмотров
+
+```javascript
+const recentlyViewed = useCookieRef<number[]>('recently-viewed', [], {
+  expires: 30
+})
+
+const addToRecent = (productId) => {
+  const recent = [productId, ...recentlyViewed.value.filter(id => id !== productId)]
+  recentlyViewed.value = recent.slice(0, 10) // Храним последние 10
+}
+```
+
+## Преимущества синхронизации через Broadcast Channel
+
+**В отличие от обычного ref с cookie:**
+- ✅ Мгновенная синхронизация между вкладками (не требуется перезагрузка)
+- ✅ Реальное время обновления (без задержек)
+- ✅ Эффективная передача данных (не через localStorage)
+- ✅ Изоляция сессий браузера
+
+**Механизм работы:**
+1. Изменение в одной вкладке → сохраняется в cookie
+2. Через Broadcast Channel (`__cookie:${name}`) отправляется сообщение
+3. Все остальные вкладки получают обновление мгновенно
+4. ref во всех вкладках обновляется автоматически