====== MapCore ======

Зручний шар абстракції над Leaflet для побудови інтерактивних карт. 
MapCore збирає карту на боці серверу: контейнер, центр/зум, маркери та фігури, іконки, додатковий JS - а потім віддає готовий HTML + Leaflet-скрипт через ''render()''.

===== Базовий життєвий цикл =====

  - Створити інстанс з унікальним id контейнера
  - Налаштувати центр, зум, тип шару
  - Додати [[https://www.youtube.com/watch?v=sp6qesojabQ|об'єкти]] (''addMarker'', ''addCircle'', ...)
  - Вивести ''renderContainer()'' + ''render()''

<code php>
$map = new MapCore('mymap');
$map->setCenter('48.595098,24.380122');
$map->setZoom(15);
$map->setType('roadmap'); // roadmap|satellite|hybrid|terrain

$map->addMarker('48.595098,24.380122', 'Опис точки', array(
    'icon' => 'marker.red',
    'tooltip' => 'Підказка',
    'popupTitle' => 'Заголовок',
    'popupFooter' => '<a href="?module=userprofile&username=test">Profile</a>',
    'id' => 'point-1' // опційно: ключ у JS-реєстрі ubMapMarkers
));

show_window(__('Map'), $map->renderContainer('100%', '500px') . $map->render());
</code>

Координати завжди у форматі **''"lat,lng"''**.

Більшість setter/add-методів повертають ''$this''.

===== Конфігурація карти =====

^ Метод ^ Що робить ^
| ''setCenter($coords)'' | Центр карти. Порожньо = геолокація браузера |
| ''setZoom($zoom)'' / ''setMaxZoom($z)'' | Початковий і максимальний зум |
| ''setType($type)'' | Базовий шар: roadmap / satellite / hybrid / terrain |
| ''setSearchPrefill($text)'' | Prefill у геокодері |
| ''setRememberZoom()'' / ''setRememberPosition()'' / ''setRememberLayer()'' | Збереження стану в localStorage |
| ''setClustering($bool, $opts)'' | Кластеризація маркерів |
| ''setForceCanvasMarkers($bool)'' | Canvas-рендер маркерів (для [[https://www.youtube.com/watch?v=xDDxXhKfsmc|великих карт]]) |
| ''setMarkerToggleShellEnabled()'' | Усі маркери в ''L.layerGroup'' (''ubMarkerToggleShell'') |
| ''setFpsMeter()'' | FPS-оверлей |
| ''addRawJs($js)'' / ''addScriptSrc($url)'' | Додатковий JS / зовнішні скрипти |
| ''addLocationEditor($field, $title, $formHtml)'' | Клік по карті -> координати у форму |

Частина опцій автоматично підхоплюється з ''ymaps.ini'' (tile layer, canvas render, metrics, remember layer).

===== Об'єкти на карті =====

^ Метод ^ Опис ^
| ''addMarker($coords, $popup, $opts)'' | Звичайний маркер |
| ''addDynamicMarker($coords, $title, $url, $opts)'' | Маркер з AJAX-popup (fetch URL) |
| ''addCircleMarker($coords, $radiusPx, $popup, $opts)'' | Круглий маркер з діаметром у пікселях |
| ''addCircle($coords, $radiusM, $popup, $opts)'' | Коло в метрах |
| ''addLine($a, $b, $opts)'' | Відрізок між двома точками |
| ''addPolyline($points, $popup, $opts)'' | Ламана (масив ''"lat,lng"'') |
| ''addPolygon($points, $popup, $opts)'' | Полігон |
| ''addRectangle($sw, $ne, $popup, $opts)'' | Прямокутник (SW + NE) |
| ''addGeoJSON($geoJson, $opts)'' | GeoJSON-шар (RFC 7946) |

Поширені опції фігур: ''color'', ''fillColor'', ''opacity'', ''fillOpacity'', ''weight'', ''hint'', ''popupTitle'', ''dashArray''.

===== Іконки =====

Вбудовані ключі: ''marker.blue/red/yellow/green/pink/brown/darkblue/orange/grey/black'', ''marker.building/house/camping/wifi/camera/waterfall'', ''vehicle.red/green/yellow''.

<code php>
$map->registerIcon('my.icon', 'skins/mymark.png');
$map->addMarker('48.595098,24.380122', 'Hi', array('icon' => 'my.icon'));
</code>

Статика: ''MapCore::getIconKeys()'', ''resolveIconPath()'', ''registerIconDefinition()''.

===== Композиція шарів =====

Можна зібрати об'єкти в одному інстансі і влити в інший (міні-карти, комбіновані оверлеї):

<code php>
$layer = new MapCore('tmp');
$layer->addMarker('48.595098,24.380122', 'Build');

$map = new MapCore('main');
$map->setCenter('48.595098,24.380122')->setZoom(16);
$map->injectMapObjects($layer);          // або $layer->getMapObjects()
// $map->injectMapObjects($payload, true); // replace замість append
</code>

Також: ''getPlacemarks()'' / ''injectPlacemarks()'', ''getObjectCounts()''.

===== Рендер =====

  * ''renderContainer($w, $h, $class, $options)'' - ''<div>'' контейнера
  * ''render()'' - Leaflet assets + init-скрипт карти
  * ''getContainerId()'' - DOM id інстанса

Важливо: контейнер має бути в DOM **до** виклику ''render()''.

===== Додатково =====

  * Canvas-markers і clustering разом: пріоритет у canvas, clustering ігнорується.
  * Опційний ''options['id']'' реєструє маркер у JS-реєстрі ''ubMapMarkers'' для доступу з кастомного JS.