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

<Meta title='@dxtmisha/functional/ru/Classes/Icons'/>

# Класс Icons

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

## Основные возможности

- **Глобальное кеширование** — автоматическое сохранение в window для переиспользования
- **Асинхронная загрузка** — поддержка Promise и ленивой загрузки иконок
- **Режим ожидания** — автоматическое ожидание загрузки с таймаутом
- **Автоматические пути** — генерация SVG путей по названию с префиксом @
- **Пакетное добавление** — массовое добавление иконок из объекта
- **Глобальные URL** — поддержка CDN и различных окружений
- **Проверка существования** — быстрая проверка наличия иконок
- **Список иконок** — получение всех зарегистрированных названий

## Методы проверки и получения

### `is`

Проверяет наличие иконки в коллекции.

**Параметры:**
- `index: string` — название иконки

**Возвращает:** `boolean` — true если иконка существует

```javascript
if (Icons.is('user')) {
  // иконка доступна
}
```

### `get`

Возвращает содержимое иконки с поддержкой асинхронной загрузки.

**Параметры:**
- `index: string` — название иконки
- `url?: string` — альтернативный путь хранения
- `wait?: number` — время ожидания в мс (по умолчанию 180000)

**Возвращает:** `Promise<string>` — содержимое иконки

```javascript
// Простое получение
const icon = await Icons.get('user')

// С альтернативным URL
const customIcon = await Icons.get('custom', '/assets/')

// Автоматический путь
const arrowIcon = await Icons.get('@arrow-left') // → /icons/arrow-left.svg
```

### `getNameList`

Возвращает список всех зарегистрированных иконок.

**Возвращает:** `string[]` — массив названий иконок

```javascript
const iconNames = Icons.getNameList()
console.log(iconNames) // ['user', 'home', 'settings']
```

### `getUrlGlobal`

Возвращает глобальный URL для иконок.

**Возвращает:** `string` — базовый URL

```javascript
const globalUrl = Icons.getUrlGlobal()
console.log(globalUrl) // '/icons/' или полный CDN URL
```

## Методы добавления

### `add`

Добавляет иконку в коллекцию.

**Параметры:**
- `index: string` — название иконки
- `file: IconsItem` — путь к файлу или Promise с содержимым

```javascript
// Простое добавление
Icons.add('user', '/icons/user.svg')

// SVG содержимое
Icons.add('custom', '<svg>...</svg>')

// Асинхронная загрузка
Icons.add('async', fetch('/api/icon.svg').then(r => r.text()))
```

### `addLoad`

Добавляет иконку в режиме загрузки.

**Параметры:**
- `index: string` — название иконки

```javascript
Icons.addLoad('processing')
// Иконка будет ожидать загрузки при вызове get()
```

### `addGlobal`

Добавляет глобальную иконку.

**Параметры:**
- `index: string` — название иконки
- `file: string` — относительный путь к файлу

```javascript
Icons.addGlobal('logo', 'brand/logo.svg')
// Использует getUrlGlobal() + file
```

### `addByList`

Добавляет иконки из объекта.

**Параметры:**
- `list: Record<string, IconsItem>` — объект с иконками

```javascript
const uiIcons = {
  'arrow-up': '/icons/arrow-up.svg',
  'arrow-down': '/icons/arrow-down.svg'
}
Icons.addByList(uiIcons)
```

## Методы конфигурации

### `setUrl`

Изменяет базовый путь к файлам иконок.

**Параметры:**
- `url: string` — новый базовый путь

```javascript
// Для разработки
Icons.setUrl('/dev-icons/')

// Для продакшена
Icons.setUrl('https://cdn.example.com/icons/')
```

## Практические примеры

### Инициализация иконок

```javascript
// Настройка базового URL
Icons.setUrl('/assets/icons/')

// Добавление основных иконок
Icons.addByList({
  'user': 'user.svg',
  'home': 'home.svg',
  'settings': 'settings.svg'
})

// Добавление темных иконок
Icons.addByList({
  'user-dark': 'dark/user.svg',
  'home-dark': 'dark/home.svg'
})
```

### Динамическая загрузка

```javascript
async function loadIcon(name) {
  if (!Icons.is(name)) {
    Icons.addLoad(name)
  }
  return await Icons.get(name)
}

// Использование
const userIcon = await loadIcon('user')
document.getElementById('icon').innerHTML = userIcon
```

### Компонент иконки

```javascript
class IconComponent {
  async render(iconName) {
    try {
      const iconContent = await Icons.get(iconName)
      return `<span class="icon">${iconContent}</span>`
    } catch (error) {
      return `<span class="icon-error">❌</span>`
    }
  }
}
```

Класс Icons обеспечивает эффективное управление иконками с автоматическим кешированием, асинхронной загрузкой и гибкой конфигурацией путей для различных окружений.
