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

<Meta title='@dxtmisha/ru/functional/Classes/RouterItemRef - Управление Vue Router'/>

# Класс RouterItemRef

Статическое ядро для работы с Vue Router в функциональном слое. Обеспечивает единую точку доступа к роутеру, позволяя генерировать ссылки, выполнять переходы и нормализовать пути без прямой зависимости от контекста компонента.

Это позволяет использовать возможности роутера в классах и утилитах, где недоступны хуки `useRouter` или `useRoute`.

## Ключевые особенности

- **Глобальный доступ** — сохранение экземпляра роутера для доступа из любого места приложения.
- **Безопасная генерация** — методы для создания ссылок по именам маршрутов с параметрами.
- **Нормализация** — преобразование различных форматов путей в стандартные свойства `href`.

## Использование (Настройка)

Поскольку `RouterItemRef` является статическим классом, его необходимо инициализировать один раз при создании приложения (обычно в `main.ts` или в плагине).

```typescript
import { RouterItemRef } from '@dxtmisha/functional'
import { createRouter, createWebHistory } from 'vue-router'

const router = createRouter({
  history: createWebHistory(),
  routes: [...]
})

// Установка роутера для глобального использования
RouterItemRef.set(router)
```

## Управление экземпляром

- `static get(): Router | undefined` — Возвращает текущий установленный экземпляр роутера.
- `static set(router: Router): void` — Устанавливает экземпляр роутера.
- `static setOneTime(router: Router): void` — Устанавливает экземпляр роутера только в том случае, если он еще не был установлен. Полезно для предотвращения случайной перезаписи в плагинах.

## Навигация и Ссылки

Группа методов для управления историей переходов и генерации URL.

### `push`

Выполняет программный переход на указанный маршрут. Является безопасной оберткой над `router.push`. Если роутер еще не установлен, действие будет проигнорировано.

**Параметры:**
- `to: string | RouteLocationRaw` — целевой путь или объект местоположения маршрута.

### `getLink`

Генерирует и возвращает строковый URL (href) для маршрута на основе его имени и параметров. Использует метод `router.resolve`.

**Параметры:**
- `name: string` — уникальное имя маршрута.
- `params?: any` — динамические параметры пути (params).
- `query?: any` — параметры запроса (query string).

**Возвращает:** `string | undefined` — готовый URL или `undefined`, если роутер не инициализирован.

### `getHref`

Возвращает стандартизированный объект свойств ссылки. Удобно для передачи в компоненты, ожидающие `ConstrHrefProps`.

**Параметры:**
- `name?: string` — имя маршрута.
- `params?: any` — параметры пути.
- `query?: any` — параметры запроса.

**Возвращает:** `ConstrHrefProps` — объект `{ href: string }` или `{}` (пустой объект), если имя не передано.

### `rawToHref`

Специальный метод для нормализации. Преобразует объект местоположения (если в нем указано `name`) в объект свойств ссылки.

**Параметры:**
- `to?: string | RouteLocationRaw` — необработанные данные маршрута.

**Возвращает:** `ConstrHrefProps` — результат работы `getHref` или `{}`.

## Примеры

### Генерация ссылки в коде

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

// Получение URL для страницы пользователя
const userUrl = RouterItemRef.getLink('user-profile', { id: 123 })
// Результат: '/user/123' (в зависимости от настроек роутера)

// Использование для свойств компонентов
const linkProps = RouterItemRef.getHref('catalog', undefined, { category: 'electronics' })
// Результат: { href: '/catalog?category=electronics' }
```

### Программный переход

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

const logout = () => {
    // Выполняем переход на главную страницу после выхода
    RouterItemRef.push({ name: 'home' })
}
```
