@dxtmisha/wiki 0.24.0 → 0.24.2

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

@@ -0,0 +1,248 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/functional/en/Composables/useSessionRef'/>
+
+# Composable useSessionRef
+
+Composable for creating a reactive variable synchronized with sessionStorage. Automatically manages reading and writing values to browser session storage with singleton pattern. Data persists only within the current tab/window and is deleted when it closes.
+
+## Key Features
+
+- **Two-way synchronization** — automatic sync between ref and sessionStorage
+- **Automatic persistence** — ref changes automatically saved to sessionStorage
+- **Tab isolation** — data not synchronized between tabs (unlike localStorage)
+- **Temporary storage** — data deleted when tab/browser closes
+- **Singleton pattern** — reuses ref for same keys
+- **Type safety** — full TypeScript support with generics
+- **Default values** — supports initial values and factory functions
+- **DataStorage integration** — uses DataStorage class for storage management
+
+## Function
+
+### `useSessionRef`
+
+Creates a reactive variable synchronized with sessionStorage.
+
+**Parameters:**
+- `name: string` — key name in sessionStorage
+- `defaultValue?: T | (() => T)` — default value or function to generate it (optional)
+
+**Returns:** `Ref<T | undefined>` — Vue reactive variable linked to sessionStorage
+
+```javascript
+import { useSessionRef } from '@dxtmisha/functional'
+
+// Simple usage
+const wizardStep = useSessionRef('wizard-step')
+
+// With default value
+const currentStep = useSessionRef('current-step', 1)
+
+// With factory function
+const sessionId = useSessionRef('session-id', () => Math.random().toString(36))
+```
+
+## Basic Usage
+
+### Basic Synchronization
+
+```javascript
+import { useSessionRef } from '@dxtmisha/functional'
+
+// Create ref synchronized with sessionStorage
+const wizardProgress = useSessionRef('wizard-progress', { step: 1 })
+
+// When ref changes - sessionStorage automatically updates
+wizardProgress.value = { step: 2, data: { name: 'John' } }
+
+// On page reload (in same tab) value is restored
+console.log(wizardProgress.value) // { step: 2, data: { name: 'John' } }
+
+// When tab closes, data is deleted
+```
+
+### Singleton Pattern
+
+```javascript
+// Repeated calls with same name return existing ref
+const step1 = useSessionRef('wizard-step', 1)
+const step2 = useSessionRef('wizard-step', 2)
+
+console.log(step1 === step2) // true - same ref
+
+step1.value = 3
+console.log(step2.value) // 3 - both point to same ref
+```
+
+## Usage in Components
+
+### Multi-step Wizard
+
+```javascript
+import { useSessionRef } from '@dxtmisha/functional'
+
+export default {
+  setup() {
+    const currentStep = useSessionRef('wizard-step', 1)
+    const formData = useSessionRef('wizard-data', {
+      name: '',
+      email: '',
+      phone: ''
+    })
+
+    const nextStep = () => {
+      currentStep.value++
+    }
+
+    const prevStep = () => {
+      if (currentStep.value > 1) {
+        currentStep.value--
+      }
+    }
+
+    return {
+      currentStep,
+      formData,
+      nextStep,
+      prevStep
+    }
+  }
+}
+
+// Template:
+// <div>
+//   <div v-if="currentStep === 1">
+//     <input v-model="formData.name" placeholder="Name" />
+//   </div>
+//   <div v-if="currentStep === 2">
+//     <input v-model="formData.email" placeholder="Email" />
+//   </div>
+//   <button @click="prevStep">Back</button>
+//   <button @click="nextStep">Next</button>
+// </div>
+```
+
+### Temporary Filter State
+
+```javascript
+import { useSessionRef } from '@dxtmisha/functional'
+
+export default {
+  setup() {
+    const filters = useSessionRef('search-filters', {
+      category: 'all',
+      priceMin: 0,
+      priceMax: 10000,
+      sortBy: 'name'
+    })
+
+    const resetFilters = () => {
+      filters.value = {
+        category: 'all',
+        priceMin: 0,
+        priceMax: 10000,
+        sortBy: 'name'
+      }
+    }
+
+    return { filters, resetFilters }
+  }
+}
+```
+
+## Differences from useStorageRef
+
+```javascript
+// useStorageRef - data persists between browser sessions
+const persistentTheme = useStorageRef('theme', 'light')
+// Data remains even after browser closes
+
+// useSessionRef - data deleted when tab closes
+const temporaryFilters = useSessionRef('filters', {})
+// Data deleted when tab/browser closes
+
+// useStorageRef syncs between tabs
+// useSessionRef isolated per tab
+```
+
+## Working with Data Types
+
+```javascript
+// Numbers
+const step = useSessionRef<number>('step', 1)
+step.value = 2
+
+// Booleans
+const isCompleted = useSessionRef<boolean>('completed', false)
+isCompleted.value = true
+
+// Objects
+const wizardData = useSessionRef('wizard-data', {
+  step: 1,
+  userData: {},
+  timestamp: Date.now()
+})
+
+// Arrays
+const selectedItems = useSessionRef<number[]>('selected', [])
+selectedItems.value.push(42)
+```
+
+## Usage Examples
+
+### Form Progress Persistence
+
+```javascript
+const registrationForm = useSessionRef('registration', {
+  step: 1,
+  personal: { name: '', email: '' },
+  address: { street: '', city: '' },
+  completed: false
+})
+
+// Data saved as form is filled
+registrationForm.value.personal.name = 'John'
+registrationForm.value.step = 2
+
+// On page reload (F5) data is restored
+// On tab close - everything is deleted
+```
+
+### Temporary Modal State
+
+```javascript
+const modalState = useSessionRef('modal', {
+  isOpen: false,
+  activeTab: 'details',
+  scrollPosition: 0
+})
+
+const openModal = () => {
+  modalState.value.isOpen = true
+}
+
+const closeModal = () => {
+  modalState.value.isOpen = false
+}
+```
+
+### Shopping Cart (Temporary)
+
+```javascript
+const cart = useSessionRef<CartItem[]>('temp-cart', [])
+
+const addToCart = (item: CartItem) => {
+  cart.value = [...cart.value, item]
+}
+
+const removeFromCart = (itemId: number) => {
+  cart.value = cart.value.filter(item => item.id !== itemId)
+}
+
+const clearCart = () => {
+  cart.value = []
+}
+
+// Cart is automatically cleared when tab closes
+```
+

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

@@ -0,0 +1,242 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/functional/en/Composables/useStorageRef'/>
+
+# Composable useStorageRef
+
+Composable for creating a reactive variable synchronized with localStorage. Automatically manages reading and writing values to browser local storage with caching support, cross-tab synchronization, and singleton pattern for efficient reuse.
+
+## Key Features
+
+- **Two-way synchronization** — automatic sync between ref and localStorage
+- **Automatic persistence** — ref changes automatically saved to localStorage
+- **Caching with TTL** — optional cache lifetime in seconds
+- **Cross-tab synchronization** — automatic updates when changes occur in other tabs
+- **Singleton pattern** — reuses ref for same keys
+- **Type safety** — full TypeScript support with generics
+- **Default values** — supports initial values and factory functions
+- **DataStorage integration** — uses DataStorage class for storage management
+
+## Function
+
+### `useStorageRef`
+
+Creates a reactive variable synchronized with localStorage.
+
+**Parameters:**
+- `name: string` — key name in localStorage
+- `defaultValue?: T | (() => T)` — default value or function to generate it (optional)
+- `cache?: number` — cache time in seconds (optional)
+
+**Returns:** `Ref<T | undefined>` — Vue reactive variable linked to localStorage
+
+```javascript
+import { useStorageRef } from '@dxtmisha/functional'
+
+// Simple usage
+const theme = useStorageRef('app-theme')
+
+// With default value
+const language = useStorageRef('app-language', 'en')
+
+// With factory function
+const userId = useStorageRef('user-id', () => Math.random().toString(36))
+
+// With caching (600 seconds = 10 minutes)
+const cachedData = useStorageRef('cached-data', null, 600)
+```
+
+## Basic Usage
+
+### Basic Synchronization
+
+```javascript
+import { useStorageRef } from '@dxtmisha/functional'
+
+// Create ref synchronized with localStorage
+const userTheme = useStorageRef('theme', 'light')
+
+// When ref changes - localStorage automatically updates
+userTheme.value = 'dark'
+// localStorage: { 'ui-storage__theme': '{"value":"dark","age":1234567890}' }
+
+// On page reload, value is restored
+console.log(userTheme.value) // 'dark'
+```
+
+### Singleton Pattern
+
+```javascript
+// Repeated calls with same name return existing ref
+const theme1 = useStorageRef('app-theme', 'light')
+const theme2 = useStorageRef('app-theme', 'dark')
+
+console.log(theme1 === theme2) // true - same ref
+
+theme1.value = 'blue'
+console.log(theme2.value) // 'blue' - both point to same ref
+```
+
+## Usage in Components
+
+### User Settings
+
+```javascript
+import { useStorageRef } from '@dxtmisha/functional'
+
+export default {
+  setup() {
+    const theme = useStorageRef('user-theme', 'light')
+    const fontSize = useStorageRef('font-size', 16)
+    const notifications = useStorageRef('notifications', true)
+
+    return {
+      theme,
+      fontSize,
+      notifications
+    }
+  }
+}
+
+// Template:
+// <div>
+//   <select v-model="theme">
+//     <option value="light">Light</option>
+//     <option value="dark">Dark</option>
+//   </select>
+//   <input v-model.number="fontSize" type="number" />
+//   <input v-model="notifications" type="checkbox" />
+// </div>
+```
+
+### API Data Caching
+
+```javascript
+import { useStorageRef } from '@dxtmisha/functional'
+
+export default {
+  setup() {
+    // Cache for 10 minutes (600 seconds)
+    const userData = useStorageRef('user-data', null, 600)
+
+    const loadUserData = async () => {
+      if (userData.value) {
+        console.log('Data from cache')
+        return userData.value
+      }
+
+      console.log('Loading from server')
+      const response = await fetch('/api/user')
+      userData.value = await response.json()
+      return userData.value
+    }
+
+    return { userData, loadUserData }
+  }
+}
+```
+
+## Cross-tab Synchronization
+
+```javascript
+import { useStorageRef } from '@dxtmisha/functional'
+
+// In first tab
+const counter = useStorageRef('counter', 0)
+counter.value = 5
+
+// In second tab automatically updates
+// counter.value === 5 (thanks to storage event)
+
+// In third tab
+const sameCounter = useStorageRef('counter', 0)
+console.log(sameCounter.value) // 5
+
+// Changes in any tab update all others
+sameCounter.value = 10
+// All open tabs will have counter.value === 10
+```
+
+## Working with Data Types
+
+```javascript
+// Numbers
+const count = useStorageRef<number>('count', 0)
+count.value = 42
+
+// Booleans
+const isActive = useStorageRef<boolean>('active', false)
+isActive.value = true
+
+// Objects
+const settings = useStorageRef('settings', {
+  theme: 'dark',
+  language: 'en',
+  notifications: true
+})
+settings.value.theme = 'light'
+
+// Arrays
+const items = useStorageRef<string[]>('items', [])
+items.value.push('new item')
+```
+
+## Usage Examples
+
+### Form State Persistence
+
+```javascript
+const formData = useStorageRef('contact-form', {
+  name: '',
+  email: '',
+  message: ''
+})
+
+// When filling form, data is automatically saved
+formData.value.name = 'John'
+formData.value.email = 'john@example.com'
+
+// On page reload, data is restored
+```
+
+### User Favorites
+
+```javascript
+const favorites = useStorageRef<number[]>('favorites', [])
+
+const addToFavorites = (id: number) => {
+  if (!favorites.value.includes(id)) {
+    favorites.value = [...favorites.value, id]
+  }
+}
+
+const removeFromFavorites = (id: number) => {
+  favorites.value = favorites.value.filter(fav => fav !== id)
+}
+```
+
+### Cache with Auto-refresh
+
+```javascript
+// Cache for 5 minutes
+const newsData = useStorageRef('news', null, 300)
+
+const fetchNews = async () => {
+  // If cache is valid - return saved data
+  if (newsData.value) return newsData.value
+
+  // Otherwise load fresh data
+  const response = await fetch('/api/news')
+  newsData.value = await response.json()
+  return newsData.value
+}
+
+// First call - loads from server
+await fetchNews()
+
+// Subsequent calls within 5 minutes - use cache
+await fetchNews() // From cache
+
+// After 5+ minutes - loads from server again
+```
+