@dxtmisha/wiki 0.24.0 → 0.24.2

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

@@ -0,0 +1,288 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/functional/en/Composables/useGeoIntlRef'/>
+
+# Composable useGeoIntlRef
+
+Composable for creating a reactive internationalization object. Provides methods for formatting numbers, currencies, dates and names with automatic locale detection. All methods return computed values that automatically update when input data changes.
+
+## Key Features
+
+- **Number formatting** — localized number representation with separators
+- **Currency formatting** — displaying monetary amounts with currency symbols
+- **Date formatting** — various date and time formats by regional standards
+- **Country and language names** — localized region names
+- **Relative time** — "2 days ago", "in 5 minutes", etc.
+- **Percentages and units** — formatting percentages and measurement units
+- **Reactivity** — all methods return computed that update automatically
+- **Auto locale detection** — uses user geolocation by default
+
+## Function
+
+### `useGeoIntlRef()`
+
+Creates and returns instance of `GeoIntlRef` class for working with data formatting.
+
+**Parameters:** none
+
+**Returns:** `GeoIntlRef` — object with formatting methods
+
+```javascript
+import { useGeoIntlRef } from '@dxtmisha/functional'
+
+// Create instance
+const intl = useGeoIntlRef()
+
+// All methods return ComputedRef
+const formatted = intl.number(1234.56)
+```
+
+## Number Formatting Methods
+
+### `number`
+
+Format number according to locale.
+
+**Parameters:**
+- `value: RefOrNormal<NumberOrString>` — number to format
+- `options?: Intl.NumberFormatOptions` — formatting options
+
+**Returns:** `ComputedRef<string>`
+
+```javascript
+const intl = useGeoIntlRef()
+const count = ref(1234567.89)
+
+intl.number(count) // ComputedRef<'1,234,567.89'>
+intl.number(1000, { minimumFractionDigits: 2 }) // ComputedRef<'1,000.00'>
+```
+
+### `decimal`
+
+Returns decimal separator symbol for current locale.
+
+**Returns:** `ComputedRef<string>`
+
+```javascript
+const intl = useGeoIntlRef()
+intl.decimal() // ComputedRef<'.'>  (for en-US)
+               // ComputedRef<','>  (for ru-RU)
+```
+
+### `percent`
+
+Format number as percentage.
+
+**Parameters:**
+- `value: RefOrNormal<NumberOrString>` — number to format (0.15 = 15%)
+- `options?: Intl.NumberFormatOptions` — formatting options
+
+**Returns:** `ComputedRef<string>`
+
+```javascript
+intl.percent(0.15)  // ComputedRef<'15%'>
+intl.percent(1.25)  // ComputedRef<'125%'>
+```
+
+### `percentBy100`
+
+Format number as percentage (value already in percents).
+
+**Parameters:**
+- `value: RefOrNormal<NumberOrString>` — number to format (15 = 15%)
+- `options?: Intl.NumberFormatOptions` — formatting options
+
+**Returns:** `ComputedRef<string>`
+
+```javascript
+intl.percentBy100(15)   // ComputedRef<'15%'>
+intl.percentBy100(125)  // ComputedRef<'125%'>
+```
+
+## Currency Formatting Methods
+
+### `currency`
+
+Format monetary amount.
+
+**Parameters:**
+- `value: RefOrNormal<NumberOrString>` — amount to format
+- `currencyOptions?: RefOrNormal<string | Intl.NumberFormatOptions>` — currency code or options
+- `numberOnly?: boolean` — don't show currency symbol (default `false`)
+
+**Returns:** `ComputedRef<string>`
+
+```javascript
+const intl = useGeoIntlRef()
+const price = ref(99.99)
+
+intl.currency(price, 'USD')           // ComputedRef<'$99.99'>
+intl.currency(1234.56, 'RUB')         // ComputedRef<'RUB 1,234.56'>
+intl.currency(500, 'EUR', true)       // ComputedRef<'500.00'> (no symbol)
+```
+
+### `unit`
+
+Format with measurement units.
+
+**Parameters:**
+- `value: RefOrNormal<NumberOrString>` — value to format
+- `unitOptions?: string | Intl.NumberFormatOptions` — unit or options
+
+**Returns:** `ComputedRef<string>`
+
+```javascript
+intl.unit(100, 'kilometer')  // ComputedRef<'100 km'>
+intl.unit(50, 'kilogram')    // ComputedRef<'50 kg'>
+intl.unit(1.5, 'hour')       // ComputedRef<'1.5 hr'>
+```
+
+## Date Formatting Methods
+
+### `date`
+
+Format date and time.
+
+**Parameters:**
+- `value: RefOrNormal<NumberOrStringOrDate>` — date to format
+- `type?: GeoDate` — format type ('date' | 'time' | 'datetime' | 'full' | 'long' | 'medium' | 'short')
+- `styleOptions?: Intl.DateTimeFormatOptions['month'] | Intl.DateTimeFormatOptions` — style or options
+- `hour24?: boolean` — use 24-hour format
+
+**Returns:** `ComputedRef<string>`
+
+```javascript
+const date = ref(new Date('2024-10-15 14:30:00'))
+
+intl.date(date)               // ComputedRef<'10/15/2024'>
+intl.date(date, 'time')       // ComputedRef<'2:30 PM'>
+intl.date(date, 'datetime')   // ComputedRef<'10/15/2024, 2:30 PM'>
+intl.date(date, 'full')       // ComputedRef<'Tuesday, October 15, 2024'>
+```
+
+### `relative`
+
+Format relative time ("2 days ago", "in 1 hour").
+
+**Parameters:**
+- `value: RefOrNormal<NumberOrStringOrDate>` — date to compare
+- `styleOptions?: Intl.RelativeTimeFormatStyle | Intl.RelativeTimeFormatOptions` — style ('long' | 'short' | 'narrow')
+- `todayValue?: Date` — current date (default `new Date()`)
+
+**Returns:** `ComputedRef<string>`
+
+```javascript
+const twoDaysAgo = new Date()
+twoDaysAgo.setDate(twoDaysAgo.getDate() - 2)
+
+intl.relative(twoDaysAgo)             // ComputedRef<'2 days ago'>
+intl.relative(twoDaysAgo, 'short')    // ComputedRef<'2 days ago'>
+```
+
+### `relativeLimit`
+
+Format relative time with limit. If difference exceeds limit, outputs absolute date.
+
+**Parameters:**
+- `value: RefOrNormal<NumberOrStringOrDate>` — date to format
+- `limit: number` — limit in days
+- `todayValue?: Date` — current date
+- `relativeOptions?: Intl.RelativeTimeFormatStyle | Intl.RelativeTimeFormatOptions` — relative format options
+- `dateOptions?: Intl.DateTimeFormatOptions['month'] | Intl.DateTimeFormatOptions` — date format options
+- `type?: GeoDate` — date format type
+- `hour24?: boolean` — 24-hour format
+
+**Returns:** `ComputedRef<string>`
+
+```javascript
+const threeDaysAgo = new Date()
+threeDaysAgo.setDate(threeDaysAgo.getDate() - 3)
+
+intl.relativeLimit(threeDaysAgo, 7)   // ComputedRef<'3 days ago'>
+
+const tenDaysAgo = new Date()
+tenDaysAgo.setDate(tenDaysAgo.getDate() - 10)
+
+intl.relativeLimit(tenDaysAgo, 7)     // ComputedRef<'10/05/2024'> (absolute date)
+```
+
+## Name Methods
+
+### `display`
+
+Get localized name (language, region, script, etc.).
+
+**Parameters:**
+- `value?: RefOrNormal<string>` — code to get name for
+- `typeOptions?: Intl.DisplayNamesOptions['type'] | Intl.DisplayNamesOptions` — type ('language' | 'region' | 'script' | 'currency')
+
+**Returns:** `ComputedRef<string>`
+
+```javascript
+intl.display('US', 'region')    // ComputedRef<'United States'>
+intl.display('en', 'language')  // ComputedRef<'English'>
+intl.display('USD', 'currency') // ComputedRef<'US Dollar'>
+```
+
+### `languageName`
+
+Get language name.
+
+**Parameters:**
+- `value?: RefOrNormal<string>` — language code
+- `style?: Intl.RelativeTimeFormatStyle` — display style
+
+**Returns:** `ComputedRef<string>`
+
+```javascript
+intl.languageName('en')  // ComputedRef<'English'>
+intl.languageName('de')  // ComputedRef<'German'>
+```
+
+### `countryName`
+
+Get country name.
+
+**Parameters:**
+- `value?: RefOrNormal<string>` — country code
+- `style?: Intl.RelativeTimeFormatStyle` — display style
+
+**Returns:** `ComputedRef<string>`
+
+```javascript
+intl.countryName('US')  // ComputedRef<'United States'>
+intl.countryName('GB')  // ComputedRef<'United Kingdom'>
+```
+
+## Usage Examples
+
+### Basic Usage
+
+```javascript
+import { ref } from 'vue'
+import { useGeoIntlRef } from '@dxtmisha/functional'
+
+const intl = useGeoIntlRef()
+const price = ref(1234.56)
+
+// All methods return ComputedRef
+const formatted = intl.currency(price, 'USD')
+console.log(formatted.value) // '$1,234.56'
+
+// Automatic update on change
+price.value = 2000
+console.log(formatted.value) // '$2,000.00'
+```
+
+### Reactive Parameters
+
+```javascript
+const price = ref(100)
+const currency = ref('USD')
+
+// Reactive currency and value
+const formatted = intl.currency(price, currency)
+
+currency.value = 'EUR'
+// formatted.value automatically updates
+```

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

@@ -0,0 +1,302 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/functional/en/Composables/useHashRef'/>
+
+# Composable useHashRef
+
+Composable for creating a reactive variable synchronized with URL hash. Automatically manages reading and writing values to the hash part of the URL, providing two-way synchronization between Vue reactive state and browser address bar parameters.
+
+## Key Features
+
+- **Two-way synchronization** — automatic sync between ref and URL hash
+- **Automatic persistence** — ref changes automatically reflect in URL
+- **Reactivity** — URL hash changes automatically update ref
+- **Instance caching** — reuses ref for same parameter names
+- **Type safety** — full TypeScript support with generics
+- **Default values** — supports initial values and factory functions
+- **Auto initialization** — loads existing values from URL on creation
+
+## Function
+
+### `useHashRef`
+
+Creates a reactive variable synchronized with a parameter in URL hash.
+
+**Parameters:**
+- `name: string` — parameter name in hash URL
+- `defaultValue?: T | (() => T)` — default value or function to generate it (optional)
+
+**Returns:** `Ref<T>` — Vue reactive variable linked to hash parameter
+
+```javascript
+import { useHashRef } from '@dxtmisha/functional'
+
+// Simple usage without default value
+const currentTab = useHashRef('tab')
+console.log(currentTab.value) // undefined (if hash is empty)
+
+// With default value
+const activeView = useHashRef('view', 'grid')
+console.log(activeView.value) // 'grid' (if hash doesn't contain 'view')
+
+// With factory function for default value
+const userId = useHashRef('userId', () => Math.floor(Math.random() * 1000))
+```
+
+## Basic Usage
+
+### Basic Synchronization
+
+```javascript
+import { useHashRef } from '@dxtmisha/functional'
+
+// Create ref synchronized with hash
+const currentPage = useHashRef('page', 1)
+
+// When ref changes - URL automatically updates
+currentPage.value = 2
+// URL: #page=2
+
+currentPage.value = 5
+// URL: #page=5
+
+// When URL changes manually - ref automatically updates
+// User changes URL to: #page=10
+console.log(currentPage.value) // 10
+```
+
+### Working with Multiple Parameters
+
+```javascript
+// Multiple independent hash parameters
+const searchQuery = useHashRef('q', '')
+const sortOrder = useHashRef('sort', 'asc')
+const pageNumber = useHashRef('page', 1)
+
+searchQuery.value = 'vue composables'
+sortOrder.value = 'desc'
+pageNumber.value = 3
+
+// URL: #q=vue composables;sort=desc;page=3
+
+// All parameters stay synchronized
+console.log(searchQuery.value) // 'vue composables'
+console.log(sortOrder.value)   // 'desc'
+console.log(pageNumber.value)  // 3
+```
+
+### Instance Caching
+
+```javascript
+// Repeated calls with same name return existing ref
+const tab1 = useHashRef('activeTab', 'home')
+const tab2 = useHashRef('activeTab', 'profile')
+
+console.log(tab1 === tab2) // true - same ref
+
+tab1.value = 'settings'
+console.log(tab2.value) // 'settings' - both point to same ref
+```
+
+## Usage in Components
+
+### Tab Management
+
+```javascript
+import { useHashRef } from '@dxtmisha/functional'
+
+export default {
+  setup() {
+    const activeTab = useHashRef('tab', 'overview')
+
+    return {
+      activeTab,
+      tabs: ['overview', 'details', 'settings']
+    }
+  }
+}
+
+// Template:
+// <div>
+//   <button
+//     v-for="tab in tabs"
+//     :key="tab"
+//     @click="activeTab = tab"
+//     :class="{ active: activeTab === tab }"
+//   >
+//     {{ tab }}
+//   </button>
+// </div>
+```
+
+### Pagination with State Persistence
+
+```javascript
+import { computed } from 'vue'
+import { useHashRef } from '@dxtmisha/functional'
+
+export default {
+  setup() {
+    const currentPage = useHashRef('page', 1)
+    const itemsPerPage = 20
+    const totalItems = 100
+
+    const totalPages = computed(() =>
+      Math.ceil(totalItems / itemsPerPage)
+    )
+
+    const nextPage = () => {
+      if (currentPage.value < totalPages.value) {
+        currentPage.value++
+      }
+    }
+
+    const prevPage = () => {
+      if (currentPage.value > 1) {
+        currentPage.value--
+      }
+    }
+
+    return {
+      currentPage,
+      totalPages,
+      nextPage,
+      prevPage
+    }
+  }
+}
+```
+
+### Filters and Search
+
+```javascript
+import { watch } from 'vue'
+import { useHashRef } from '@dxtmisha/functional'
+
+export default {
+  setup() {
+    const searchQuery = useHashRef('q', '')
+    const category = useHashRef('category', 'all')
+    const sortBy = useHashRef('sort', 'date')
+
+    // Watch changes to load data
+    watch([searchQuery, category, sortBy], () => {
+      console.log('Loading data with params:')
+      console.log('Search:', searchQuery.value)
+      console.log('Category:', category.value)
+      console.log('Sort:', sortBy.value)
+      // API request here
+    })
+
+    return {
+      searchQuery,
+      category,
+      sortBy
+    }
+  }
+}
+```
+
+## Working with Data Types
+
+### Numeric Values
+
+```javascript
+// Hash automatically converts types
+const pageNumber = useHashRef<number>('page', 1)
+
+pageNumber.value = 5
+// URL: #page=5
+
+// When loading from URL, string is automatically converted
+// URL: #page=10
+console.log(typeof pageNumber.value) // 'number'
+console.log(pageNumber.value)        // 10
+```
+
+### Boolean Values
+
+```javascript
+const isActive = useHashRef<boolean>('active', false)
+
+isActive.value = true
+// URL: #active=true
+
+// Automatic conversion from string
+// URL: #active=false
+console.log(typeof isActive.value) // 'boolean'
+console.log(isActive.value)        // false
+```
+
+### Objects and Arrays
+
+```javascript
+// For complex types, serialization is used
+const filters = useHashRef('filters', { min: 0, max: 100 })
+
+filters.value = { min: 20, max: 80 }
+// URL will contain serialized representation
+
+// Values are restored on load
+console.log(filters.value) // { min: 20, max: 80 }
+```
+
+## Integration with Hash Class
+
+The composable uses `Hash` class to manage URL hash:
+
+```javascript
+import { Hash } from '@dxtmisha/functional'
+
+// Direct class usage
+Hash.set('tab', 'profile')
+console.log(Hash.get('tab')) // 'profile'
+
+// useHashRef automatically syncs with Hash
+const tab = useHashRef('tab')
+console.log(tab.value) // 'profile'
+
+// Changes via Hash reflect in ref
+Hash.set('tab', 'settings')
+console.log(tab.value) // 'settings'
+```
+
+## Usage Examples
+
+### Form State Persistence
+
+```javascript
+const formData = {
+  name: useHashRef('name', ''),
+  email: useHashRef('email', ''),
+  role: useHashRef('role', 'user')
+}
+
+// When filling form, state is saved to URL
+formData.name.value = 'John'
+formData.email.value = 'john@example.com'
+formData.role.value = 'admin'
+
+// URL: #name=John;email=john@example.com;role=admin
+
+// On page reload, state is restored
+```
+
+### Modal Window Management
+
+```javascript
+const modalOpen = useHashRef('modal', null)
+
+const openModal = (modalName) => {
+  modalOpen.value = modalName
+  // URL: #modal=confirmation
+}
+
+const closeModal = () => {
+  modalOpen.value = null
+  // URL: #modal=null or hash is cleared
+}
+
+// Browser "Back" button closes modal
+```
+