Migration from v1 (matplotlib) to v2 (SVG)
===========================================

The import statement is unchanged::

   from mappyng import Map

The constructor signature is preserved.  The drawing API, however, is now
**object-based**: instead of ``m.add_choropleth(gdf, {...})`` you build a
layer and add it with ``m.add(ChoroplethLayer(gdf, ...))``.  The dict-based
``add_*`` helpers have been removed (see :doc:`../guides/quickstart`).
The parameter names below still apply; they are now keyword arguments of
the corresponding layer class.

Renamed parameters
------------------

.. list-table::
   :header-rows: 1
   :widths: 25 25 50

   * - v1 parameter
     - v2 parameter
     - Notes
   * - ``symbol["alpha"]``
     - ``fill_opacity``
     - Proportional and situation layers.
   * - ``symbol["edgecolors"]``
     - ``stroke``
     - Proportional and situation layers.
   * - ``symbol["linewidth"]``
     - ``stroke_width``
     - Proportional and situation layers.
   * - ``line_color`` (leader)
     - ``leader_color``
     - ProportionalLegendConfig.
   * - ``line_width`` (leader)
     - ``leader_width``
     - ProportionalLegendConfig.
   * - ``line_style`` (leader)
     - ``leader_dash``
     - SVG dasharray string instead of matplotlib line style.
   * - ``line_alpha`` (leader)
     - ``leader_opacity``
     - ProportionalLegendConfig.
   * - ``circle_color``
     - ``circle_fill``
     - ProportionalLegendConfig.
   * - ``rounding``
     - ``decimals``
     - Legend label decimal places.
   * - ``edgecolor`` (choropleth)
     - ``stroke``
     - ChoroplethLayer.
   * - ``linewidth`` (choropleth)
     - ``stroke_width``
     - ChoroplethLayer.

Removed parameters
------------------

These v1 parameters are not available in v2:

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - v1 parameter
     - Reason
   * - ``symbol["marker"]`` (non-circle shapes in proportional)
     - v2 proportional symbols are always circles.
   * - ``symbol["zorder"]``
     - Z-order is managed globally by :class:`~mappyng.config.ZOrderConfig`.
   * - ``adjust_size``
     - v2 uses ``max_radius`` for auto-scaling; fixed scale via ``reference_radius``.
   * - ``units`` (legend position)
     - v2 always uses SVG pixel coordinates.
   * - PNG custom markers (``situation.py``)
     - v2 is SVG-native only.  Use custom SVG files instead.

New parameters in v2
--------------------

These parameters are not present in v1:

.. list-table::
   :header-rows: 1
   :widths: 25 25 50

   * - Parameter
     - Method / class
     - Description
   * - ``font_scale``
     - :class:`~mappyng.Map`
     - Global font size multiplier.
   * - ``reference_radius``
     - ProportionalLayer
     - Fixed circle radius in SVG px (replaces ``reference_size``).
   * - ``num_values``
     - ProportionalLegendConfig
     - Number of auto-generated legend values.
   * - ``circle_fill_opacity``
     - ProportionalLegendConfig
     - Legend circle fill opacity.
   * - ``columns_n`` / ``col_gap``
     - SituationLegendConfig
     - Multi-column legend layout.
   * - ``hatch_style``
     - ChoroplethLegendConfig
     - SVG hatch pattern for legend swatches.
   * - ``hover_opacity``
     - ``to_interactive``
     - Convenience alias for hover effect opacity.
   * - ``label_position`` / ``label_format``
     - ChoroplethLegendConfig (horizontal)
     - Label centering and range formatting for horizontal legends.

Tile basemaps
-------------

v1 used ``contextily`` (matplotlib-based).  v2 downloads tiles directly::

   # v1
   import contextily as cx
   cx.add_basemap(ax, source=cx.providers.CartoDB.Positron)

   # v2
   from mappyng import TileLayer
   m.add(TileLayer(source="cartodb_positron"))

Requires ``pip install mappyng[tile]``.

Label placement
---------------

v1 used ``adjustText`` (matplotlib).  v2 uses a pure Python simulated-annealing
implementation with geometric obstacle avoidance::

   # v1
   m.add_toponyms(gdf, column="nom", max_labels=20)

   # v2
   from mappyng import LabelLayer
   m.add(LabelLayer(gdf, column="nom", max_labels=20, n_sweeps=50))

Exceptions
----------

v2 exposes a typed exception hierarchy not present in v1::

   from mappyng.errors import MapError, DataError, RenderError