import {Meta} from '@storybook/addon-docs/blocks'

<Meta title='@dxtmisha/ru/functional/# Реактивные хуки (Composables)'/>

# Реактивные хуки (Composables)

Набор инструментов для работы с браузерными API, хранилищами и интернационализацией в реактивном стиле **Vue 3 (Composition API)**.

## Особенности

Основная идея данных хуков — предоставить простой и надежный интерфейс для работы с внешними данными и состоянием. Они автоматически синхронизируют значения с хранилищами, следят за изменениями в других вкладках и обеспечивают мгновенное обновление интерфейса при смене глобальных настроек (например, языка или валюты).

## Доступные хуки

### Хранение данных
- `useStorageRef` — Реактивная обертка над `localStorage`. Поддерживает время жизни (cache) и синхронизацию между вкладками.
- `useSessionRef` — Работа с `sessionStorage`.
- `useCookieRef` — Управление куками (Cookies) в реактивном стиле.

### Интернационализация (I18n)
- `useTranslateRef` — Реактивное получение строк перевода. Автоматически обновляется при смене языка в `GeoRef`.
- `useGeoIntlRef` — Форматирование чисел, валют и дат с учетом текущей локали.

### Работа с данными и поиск
- `useSearchRef` — Клиентский поиск по массивам данных с поддержкой фильтрации по нескольким колонкам.
- `useFormattersRef` — Массовое форматирование списков объектов по заданным правилам.

### Браузерные API и Состояние
- `useBroadcastValueRef` — Передача и синхронизация данных между окнами/вкладками браузера через `BroadcastChannel`.
- `useHashRef` — Реактивное управление хешем в URL (`window.location.hash`).
- `useLoadingRef` — Удобное управление состояниями загрузки (локальными и глобальными).

## Как с ними работать

Хуки разработаны так, чтобы минимизировать количество шаблонного кода. Например, при работе с локальным хранилищем вам не нужно вручную вызывать `getItem` и `setItem`. Достаточно создать переменную, и любые изменения в ней будут автоматически сохранены в `localStorage`.

```typescript
import { useStorageRef } from '@dxtmisha/functional'

// Значение 'theme' будет автоматически сохраняться и загружаться
const theme = useStorageRef('theme', 'light')

const toggleTheme = () => {
  theme.value = theme.value === 'light' ? 'dark' : 'light'
}
```

Для интернационализации используется связка управляющих классов и хуков. Если вы измените язык через `GeoRef.set()`, все переменные, созданные через `useTranslateRef`, моментально обновят свои значения во всем приложении без перезагрузки страницы.

```typescript
import { useTranslateRef, useGeoIntlRef } from '@dxtmisha/functional'

const title = useTranslateRef('main.title')
const intl = useGeoIntlRef()

// Отформатированная цена будет сама меняться при смене валюты или языка
const priceDisplay = intl.currency(12500, 'RUB')
```

Хуки поиска и форматирования (`useSearchRef`, `useFormattersRef`) часто используются как строительные блоки для более сложных инструментов, таких как `useApiManagementRef`, но могут применяться и самостоятельно для обработки локальных массивов данных.

```typescript
import { ref } from 'vue'
import { useSearchRef } from '@dxtmisha/functional'

const items = ref([{ name: 'Яблоко' }, { name: 'Банан' }])
const search = ref('')

const { listSearch } = useSearchRef(items, ['name'], search)
// listSearch всегда содержит только отфильтрованные элементы
```

Такой подход позволяет строить интерфейсы декларативно: вы описываете, какие данные вам нужны и как они должны быть связаны, а хуки берут на себя всю работу по синхронизации и обновлению.
