@dxtmisha/wiki 0.24.2 → 0.24.3

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

@@ -0,0 +1,307 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/functional/en/Classes/BroadcastMessage'/>
+
+# BroadcastMessage Class
+
+A class for handling BroadcastChannel messaging between browser tabs/windows. Enables real-time communication across different contexts of the same origin with automatic channel naming and message handling.
+
+## Key Features
+
+- **Cross-tab communication** — send and receive messages between browser tabs and windows
+- **Automatic channel naming** — unique channel names per browser instance stored in localStorage
+- **Type-safe messaging** — full TypeScript support with generic message types
+- **Callback-based handling** — flexible message handling through callback functions
+- **Error handling** — graceful error handling with console logging
+- **SSR-safe** — automatically detects DOM runtime environment
+
+## Basic Usage
+
+### Constructor
+
+Creates a new BroadcastMessage instance with specified channel name and optional callback.
+
+**Parameters:**
+- `name: string` — channel name identifier
+- `callback?: (event: MessageEvent<Message>) => void` — optional callback for received messages
+
+```javascript
+import { BroadcastMessage } from '@dxtmisha/functional'
+
+// Create channel with callback
+const channel = new BroadcastMessage('user-updates', (event) => {
+  console.log('Received message:', event.data)
+})
+
+// Create channel without callback (can be set later)
+const notifications = new BroadcastMessage('notifications')
+```
+
+### `post`
+
+Sends a message to all connected tabs/windows on the same channel.
+
+**Parameters:**
+- `message: Message` — message to broadcast
+
+**Returns:** `this` — for method chaining
+
+```javascript
+import { BroadcastMessage } from '@dxtmisha/functional'
+
+const userChannel = new BroadcastMessage('user-updates')
+
+// Send simple message
+userChannel.post({ type: 'login', userId: 123 })
+
+// Method chaining
+userChannel
+  .post({ type: 'status', value: 'online' })
+  .post({ type: 'activity', timestamp: Date.now() })
+```
+
+### `setCallback`
+
+Sets or updates the callback function for handling received messages.
+
+**Parameters:**
+- `callback: (event: MessageEvent<Message>) => void` — callback function
+
+**Returns:** `this` — for method chaining
+
+```javascript
+import { BroadcastMessage } from '@dxtmisha/functional'
+
+const channel = new BroadcastMessage('app-events')
+
+// Set callback later
+channel.setCallback((event) => {
+  console.log('Event received:', event.data)
+})
+
+// Update callback
+channel.setCallback((event) => {
+  if (event.data.type === 'refresh') {
+    location.reload()
+  }
+})
+```
+
+## Advanced Examples
+
+### Cross-Tab State Synchronization
+
+```javascript
+import { BroadcastMessage } from '@dxtmisha/functional'
+import { ref } from 'vue'
+
+// Create reactive state
+const userStatus = ref('offline')
+
+// Create broadcast channel
+const statusChannel = new BroadcastMessage('user-status', (event) => {
+  // Update local state when other tabs broadcast changes
+  userStatus.value = event.data.status
+  console.log('Status updated from another tab:', event.data.status)
+})
+
+// Function to update status and broadcast to other tabs
+function updateStatus(newStatus) {
+  userStatus.value = newStatus
+  statusChannel.post({ status: newStatus, timestamp: Date.now() })
+}
+
+// Usage
+updateStatus('online')  // Updates this tab and notifies others
+```
+
+### Multi-Tab Shopping Cart
+
+```javascript
+import { BroadcastMessage } from '@dxtmisha/functional'
+
+// Define message types
+interface CartMessage {
+  action: 'add' | 'remove' | 'clear'
+  productId?: number
+  quantity?: number
+}
+
+// Create channel with typed messages
+const cartChannel = new BroadcastMessage<CartMessage>('shopping-cart')
+
+// Set up message handler
+cartChannel.setCallback((event) => {
+  const { action, productId, quantity } = event.data
+
+  switch (action) {
+    case 'add':
+      console.log(`Adding ${quantity} of product ${productId}`)
+      addToCart(productId, quantity)
+      break
+    case 'remove':
+      console.log(`Removing product ${productId}`)
+      removeFromCart(productId)
+      break
+    case 'clear':
+      console.log('Clearing cart')
+      clearCart()
+      break
+  }
+})
+
+// Broadcast cart updates
+function addProduct(productId, quantity) {
+  addToCart(productId, quantity)
+  cartChannel.post({ action: 'add', productId, quantity })
+}
+```
+
+### Authentication State Sync
+
+```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('User logged in:', event.data.userId)
+      location.reload()
+      break
+
+    case 'logout':
+      console.log('User logged out, redirecting...')
+      localStorage.removeItem('auth-token')
+      window.location.href = '/login'
+      break
+
+    case 'token-refresh':
+      console.log('Token refreshed')
+      localStorage.setItem('auth-token', event.data.token)
+      break
+  }
+})
+
+// Broadcast login
+function handleLogin(userId, token) {
+  localStorage.setItem('auth-token', token)
+  authChannel.post({ type: 'login', userId, token })
+}
+
+// Broadcast logout
+function handleLogout() {
+  localStorage.removeItem('auth-token')
+  authChannel.post({ type: 'logout' })
+}
+```
+
+### Real-Time Notifications
+
+```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')
+
+// Set up notification handler
+notificationChannel.setCallback((event) => {
+  const notification = event.data
+
+  // Display notification in all tabs
+  showNotification(notification.title, notification.message, notification.type)
+
+  if (notification.type === 'error') {
+    playErrorSound()
+  }
+})
+
+// Send notification to all tabs
+function broadcastNotification(title, message, type = 'info') {
+  const notification = {
+    id: crypto.randomUUID(),
+    title,
+    message,
+    type,
+    timestamp: Date.now()
+  }
+
+  notificationChannel.post(notification)
+}
+
+// Usage
+broadcastNotification('New Message', 'You have a new message from John', 'info')
+```
+
+## Implementation Details
+
+### Unique Channel Naming
+
+Each browser instance generates a unique identifier stored in localStorage (`__broadcast-name`). This ensures that channels are isolated between different browser instances while allowing communication within the same instance across tabs.
+
+```javascript
+// Channel name format: name_{random_7_digits}__your-channel-name
+// Example: name_1234567__user-updates
+```
+
+### Error Handling
+
+BroadcastMessage gracefully handles errors and logs them to console:
+
+```javascript
+const channel = new BroadcastMessage('my-channel')
+// If BroadcastChannel is not supported or initialization fails,
+// error is logged: "BroadcastMessage my-channel: [error details]"
+```
+
+### SSR Compatibility
+
+The class automatically detects DOM runtime environment using `isDomRuntime()`, making it safe to use in SSR/SSG contexts where BroadcastChannel API is not available.
+
+## Type Safety
+
+```typescript
+import { BroadcastMessage } from '@dxtmisha/functional'
+
+// Define your message structure
+interface UserUpdate {
+  userId: number
+  action: 'online' | 'offline' | 'typing'
+  timestamp: number
+}
+
+// Create typed channel
+const channel = new BroadcastMessage<UserUpdate>('users')
+
+// TypeScript ensures type safety
+channel.post({
+  userId: 123,
+  action: 'online',
+  timestamp: Date.now()
+}) // ✓ Valid
+
+channel.post({ invalid: 'data' }) // ✗ TypeScript error
+```
+
+## Browser Compatibility
+
+BroadcastChannel API is supported in:
+- Chrome/Edge 54+
+- Firefox 38+
+- Safari 15.4+
+- Opera 41+
+
+For older browsers, consider using a polyfill or fallback mechanism.
+

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/mdx/Badge/badge.en.mdx

@@ -1,11 +1,89 @@
 ## Description
 
-The Badge component is a small visual indicator used to display status, count, or notifications on interface elements. It provides a compact way to convey important information without taking up much space.
+Compact visual indicator for displaying status, notification counts, or markers on interface elements with support for various display modes and automatic overflow management.
 
-### Key Features
+Badge provides a universal solution for creating informative indicators with flexible content configuration, positioning, and appearance. The component supports displaying text, numbers with maximum value limits, icons, and dot indicators, automatically hides when content is absent, and integrates with the slot system for customization.
 
-- **Status indication**: Display different states with color variants
-- **Content flexibility**: Show text, numbers, or leave empty for dot indicator
-- **Smart overflow**: Automatically handle large numbers with max value display
-- **Positioning**: Flexible placement relative to parent elements
-- **Accessibility**: Built-in support for screen readers and keyboard navigation
+**Key features:**
+
+- Multiple display modes (text, numbers, icons, dot indicator)
+- Automatic overflow management with maximum value configuration
+- Flexible positioning relative to parent elements (overlap, vertical, horizontal)
+- Automatic hiding when content is absent (dot, icon, label)
+- Integration with LabelNumberInclude for numeric value processing
+- Icon support through IconInclude
+- Color variants for different status types
+- Visibility control via hide property
+- Customization through slots for complete content control
+
+**Common use cases:**
+
+- Unread notification count indicators
+- Status markers on user avatars (online/offline)
+- Item counters in shopping carts or lists
+- New message indicators in chats
+- Status markers on product cards
+- Visual hints about available updates
+- Numeric indicators on tabs and menu items
+
+```html
+<script setup>
+import { ref } from 'vue'
+
+const cartCount = ref(5)
+const unreadMessages = ref(127)
+const isOnline = ref(true)
+
+const addToCart = () => {
+  cartCount.value++
+}
+</script>
+
+<template>
+  <div class="badge-examples">
+    <!-- Basic badge with number -->
+    <div style="position: relative; display: inline-block;">
+      <IconButton icon="shopping_cart" @click="addToCart"/>
+      <Badge :label="cartCount"/>
+    </div>
+
+    <!-- Badge with maximum value limit -->
+    <div style="position: relative; display: inline-block;">
+      <IconButton icon="notifications"/>
+      <Badge :label="unreadMessages" :label-max="99"/>
+    </div>
+
+    <!-- Dot status indicator -->
+    <div style="position: relative; display: inline-block;">
+      <Avatar src="/user-avatar.jpg"/>
+      <Badge
+        dot
+        :selected="isOnline"
+        overlap="circular"
+      />
+    </div>
+
+    <!-- Badge with icon and text -->
+    <div style="position: relative; display: inline-block;">
+      <Button>Profile</Button>
+      <Badge
+        icon="verified"
+        label="Pro"
+        overlap="static"
+      />
+    </div>
+
+    <!-- Badge with custom positioning -->
+    <div style="position: relative; display: inline-block;">
+      <Card>Content</Card>
+      <Badge
+        label="New"
+        vertical="bottom"
+        horizontal="left"
+      />
+    </div>
+  </div>
+</template>
+```
+
+> Badge is designed as a universal UI component for creating compact visual indicators with comprehensive support for various content types, automatic display management, and flexible positioning settings.