# Map Component

## Описание

Карта - это UI-компонент, который позволяет отображать географическую информацию с маркерами устройств GPS. Компонент поддерживает различные настройки отображения, темы оформления, настройки таймаута маркеров и другие параметры через систему пропсов.

## Пропсы

| Название          | Тип                                            | По умолчанию          | Описание                                                                                                                                                          |
| ----------------- | ---------------------------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | `string`                                       | `crypto.randomUUID()` | Уникальный идентификатор компонента                                                                                                                               |
| `wrapperClass`    | `string`                                       | `""`                  | Дополнительные CSS-классы для обертки компонента                                                                                                                  |
| `label`           | `object`                                       | `-`                   | Настройки заголовка компонента                                                                                                                                    |
| `label.name`      | `string`                                       | `""`                  | Текст заголовка компонента                                                                                                                                        |
| `label.class`     | `string`                                       | `""`                  | CSS-классы для стилизации текста заголовка                                                                                                                        |
| `data`            | `IDeviceGNSS \| null`                          | `$bindable()`         | Данные GPS устройства для отображения на карте (обязательный проп); поддерживает двустороннее связывание — после обработки компонент сбрасывает значение в `null` |
| `data.NavLat`     | `number`                                       | `-`                   | Широта устройства                                                                                                                                                 |
| `data.NavLon`     | `number`                                       | `-`                   | Долгота устройства                                                                                                                                                |
| `data.NavAlt`     | `number`                                       | `-`                   | Высота устройства                                                                                                                                                 |
| `data.DevName`    | `string`                                       | `-`                   | Имя устройства                                                                                                                                                    |
| `data.DevSN`      | `string`                                       | `-`                   | Серийный номер устройства                                                                                                                                         |
| `data.NavHeading` | `number`                                       | `-`                   | Направление движения устройства                                                                                                                                   |
| `data.NavSatUse`  | `number`                                       | `-`                   | Количество используемых спутников                                                                                                                                 |
| `markerIcon`      | `ConstructorOfATypedSvelteComponent \| string` | `undefined`           | Иконка для маркера устройства                                                                                                                                     |
| `trackEnabled`    | `boolean`                                      | `$bindable(false)`    | Включает отрисовку траектории движения устройств; переключатель также доступен прямо на карте                                                                     |
| `trackLength`     | `number`                                       | `$bindable(1000)`     | Максимальное количество последних точек в траектории на устройство (100 / 500 / 1000 / 5000 / 10000 / 50000); также настраивается прямо на карте                  |

## События

Компонент не генерирует специфические события, но принимает данные GPS через пропс `data`.

## Примеры

### Базовое использование

```svelte
<script>
  import * as UI from "poe-svelte-ui-lib"

  let gpsData = {
    NavLat: 50.4501,
    NavLon: 30.5234,
    NavAlt: 150,
    DevName: "Device A",
    DevSN: "SN-12345678",
    NavHeading: 45,
    NavSatUse: 8,
  }
</script>

<div class="h-150">
  <UI.Map label={{ name: "Карта" }} {data} />
</div>
```

### С пользовательской иконкой маркера

```svelte
<script>
  import * as UI from "poe-svelte-ui-lib"
  import CustomMarkerIcon from "./icons/CustomMarkerIcon.svelte"

  let gpsData = {
    NavLat: 48.8566,
    NavLon: 2.3522,
    NavAlt: 35,
    DevName: "Paris Device",
    DevSN: "SN-PARIS001",
    NavHeading: 90,
    NavSatUse: 12,
  }
</script>

<UI.Map label={{ name: "Карта с кастомной иконкой" }} {data} markerIcon={CustomMarkerIcon} />
```

## Внутренняя архитектура

### Реактивность

- Переменная `devices` хранит список отображаемых устройств на карте
- Переменная `isCopied` управляет состоянием копирования информации
- Переменная `isDarkMode` определяет тему оформления карты
- Переменная `markerTimeout` управляет временем отображения свежих маркеров

### Сторы и зависимости

- Используется стор `twMerge` для объединения Tailwind CSS классов
- Используется библиотека `MapLibre` для отображения карты
- Используется `fade` из `svelte/transition` для анимации копирования

### Директивы

- `bind:data` для получения новых данных GPS
- `$effect` для обработки изменения данных и добавления/обновления устройств
- `onMount` и `onDestroy` для управления слушателями событий темы
- `bind:value` для управления настройками таймаута

### Слоты

- Компонент не использует внешних слотов

## Конструктор свойств (MapProps.svelte)

### Описание

Компонент `MapProps.svelte` предоставляет визуальный интерфейс для редактирования свойств компонента карты. Поддерживает два режима отображения: для конструктора и для редактирования.

### Пропсы конструктора

| Название           | Тип                                                                                                                                 | По умолчанию | Описание                                                |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------- |
| `component`        | `UIComponent & { properties: Partial<IMapProps> }`                                                                                  | `-`          | Объект компонента с его свойствами                      |
| `onPropertyChange` | `(updates: Partial<{ properties?: string \| object; name?: string; access?: string; eventHandler?: IUIComponentHandler }>) => void` | `-`          | Коллбэк для обновления свойств компонента               |
| `forConstructor`   | `boolean`                                                                                                                           | `true`       | Режим отображения (для конструктора или редактирования) |

### Особенности конструктора

- Предоставляет визуальные элементы управления для всех доступных свойств
- Поддерживает выбор иконки для маркера устройства
- Включает настройки доступа и переменной устройства
- Имеет различные наборы полей в зависимости от режима (`forConstructor`)
- Использует систему локализации через `$T('constructor.props.*')`

## Заметки

### Адаптивность

- Компонент использует Tailwind CSS для адаптивного дизайна
- Карта автоматически адаптируется под размер контейнера
- Используются относительные единицы измерения для обеспечения масштабируемости

### Ограничения

- Для корректного отображения требуется подключение к интернету
- Компонент зависит от внешней библиотеки `MapLibre`
- Маркеры автоматически исчезают после истечения времени таймаута

### Производительность

- Компонент использует оптимизации Svelte для минимизации перерисовок
- Устройства удаляются из списка при истечении времени таймаута
- Используется эффективное объединение классов через `twMerge`