@dxtmisha/wiki 0.24.2 → 0.25.1

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

@@ -45,6 +45,42 @@ applyTemplate('This is [bold]bold text[/bold]', { bold: '<b>[content]</b>' }) //
 applyTemplate('Text with [red]colored[/red] word', { red: '<span style="color:red">[content]</span>' })
 ```
 
+## `blobToBase64`
+
+Converts a Blob to a Base64 string (data URL).
+
+**Parameters:**
+- `blob: Blob` — Blob object to convert
+
+```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='
+
+// Using with images
+const imageBlob = new Blob([imageData], { type: 'image/png' })
+const imageBase64 = await blobToBase64(imageBlob)
+// 'data:image/png;base64,iVBORw0KGgo...'
+```
+
+
+## `encodeAttribute`
+
+Encodes special characters in a string for safe use in HTML attributes. Converts characters `&`, `<`, `>`, `"`, `'` into corresponding HTML entities to prevent XSS attacks and ensure correct display.
+
+**Parameters:**
+- `text: string` — text to encode
+
+```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`
 
 Recursively replaces values in an object or array.
@@ -78,6 +114,37 @@ replaceTemplate('User [id]: [name]', {id: '123', name: 'John'}) // 'User 123: Jo
 replaceTemplate('Time: [time]', {time: () => new Date().toLocaleString()}) // with function
 ```
 
+## `resizeImageByMax`
+
+Resizes an image to fit within a maximum size constraint.
+
+**Parameters:**
+- `image: HTMLImageElement | string` — image element or URL
+- `maxSize: number` — maximum size for width or height
+- `type: 'auto' | 'width' | 'height'` — resize type (default 'auto')
+- `typeData?: string` — data type for the resulting image (e.g., 'image/png', 'image/jpeg')
+
+```javascript
+import { resizeImageByMax } from '@dxtmisha/functional'
+
+// Automatic scaling (by larger dimension)
+const image = document.querySelector('img')
+const resized = resizeImageByMax(image, 800) // data URL
+// Image 1200x800 becomes 800x533
+
+// Scale by width
+resizeImageByMax(image, 600, 'width')
+// Width will be 600px, height proportional
+
+// Scale by height
+resizeImageByMax(image, 400, 'height')
+// Height will be 400px, width proportional
+
+// With specified data type
+resizeImageByMax(image, 1024, 'auto', 'image/jpeg')
+// Returns JPEG data URL
+```
+
 ## `secondToTime`
 
 Converts seconds to time format (hours:minutes:seconds).

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

@@ -37,6 +37,31 @@ const copy = copyObject(original)
 copy.data.age = 25 // original.data.age remains 30
 ```
 
+## `copyObjectLite`
+
+Creates a shallow copy of a simple object. If the `source` parameter is passed, creates a new object and merges `value` and `source`.
+
+**Parameters:**
+- `value: T` — object to copy
+- `source?: any` — additional properties to copy (optional)
+
+```javascript
+import { copyObjectLite } from '@dxtmisha/functional'
+
+const original = { name: 'John', age: 30 }
+const copy = copyObjectLite(original) // { name: 'John', age: 30 }
+
+// With additional properties
+const extended = copyObjectLite(original, { city: 'Moscow' })
+// { name: 'John', age: 30, city: 'Moscow' }
+
+// Overriding properties
+const overridden = copyObjectLite(original, { age: 25 })
+// { name: 'John', age: 25 }
+```
+
+**Note:** This is a shallow copy — nested objects retain references to the originals. For deep cloning use `copyObject`, `structuredClone` or `_.cloneDeep`.
+
 ## `forEach`
 
 Universal iteration function for arrays, objects and Map.

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

@@ -228,7 +228,7 @@ const withoutTz = datetime.standard(false)
 
 ### Vue Component with Reactive Date
 
-```vue
+```html
 <template>
   <div>
     <span>{{ datetime.getYear() }}/{{ datetime.getMonth() + 1 }}/{{ datetime.getDay() }}</span>

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

@@ -259,7 +259,7 @@ const eventRef = new EventRef(buttonRef, containerRef, 'click')
 
 ### Vue Component with Reactive Events
 
-```vue
+```html
 <template>
   <button ref="buttonEl" @click="handleClick">Click me</button>
   <input ref="inputEl" placeholder="Type...">

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

@@ -6,6 +6,62 @@ import {Meta} from '@storybook/addon-docs/blocks'
 
 A set of functions for universal execution of synchronous and asynchronous operations.
 
+## `computedByLanguage`
+
+Creates a reactive computed property whose value depends on the current language and specified conditions.
+
+**Parameters:**
+- `getter: ComputedGetter<R>` — function that returns the main value depending on the language
+- `getterNone: R | (() => R)` — alternative value if conditions are not met or getter returns undefined (default undefined)
+- `conditions: () => boolean` — condition for calling the main getter (optional)
+- `debugOptions: DebuggerOptions` — Vue debug options (optional)
+
+```javascript
+import { computedByLanguage } from '@dxtmisha/functional'
+import { ref } from 'vue'
+
+// Simple example with translations
+const title = computedByLanguage(
+  () => {
+    const lang = GeoRef.get().value
+    return lang === 'ru' ? 'Заголовок' : 'Title'
+  },
+  'Default Title'
+)
+
+// With condition
+const description = computedByLanguage(
+  () => {
+    const lang = GeoRef.get().value
+    const translations = {
+      ru: 'Описание на русском',
+      en: 'Description in English'
+    }
+    return translations[lang]
+  },
+  () => 'Default description',
+  () => showDescription.value // show condition
+)
+
+// Usage in component
+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`
 
 Executes a function and returns its result, or returns input data if it's not a function.
@@ -127,3 +183,5 @@ export default {
   }
 }
 ```
+
+

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

@@ -162,7 +162,7 @@ countryCode.value = 'ru-RU'
 
 ### Vue Component with Country Flags
 
-```vue
+```html
 <template>
   <div class="country-selector">
     <div class="current-country">

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

@@ -291,7 +291,7 @@ const daysList = intl.weekdays('long')
 
 ### Vue Component with Localization
 
-```vue
+```html
 <template>
   <div class="localized-content">
     <h2>{{ intl.countryName('US') }}</h2>

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

@@ -141,7 +141,7 @@ const flag = new GeoFlagRef() // will use de-DE
 
 ### Vue Component with Global Geolocation
 
-```vue
+```html
 <template>
   <div class="geo-info">
     <h2>Current Location</h2>
@@ -202,7 +202,7 @@ GeoRef.set(userLocale)
 
 ### Global Locale Provider
 
-```vue
+```html
 <!-- App.vue -->
 <template>
   <div class="app">