foliplus 0.1.0__py3-none-any.whl

foliplus/Fullscreen.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from ._cdn import LEAFLET_FULLSCREEN
+from ._typing import Position
+from .base import BaseControl
+from .locale import LocaleConfig
+
+
+class Fullscreen(BaseControl):
+    """Fullscreen control that hides other map components when entering fullscreen.
+
+    When toggling fullscreen, other controls (HeatmapControl, LayerControl, ScaleControl
+    , MapSearch, MeasureControl, etc.), inside ``.leaflet-control-container`` are
+    automatically hidden/shown for a cleaner view.
+
+    Parameters
+    ----------
+    position : str, default "bottomright"
+        One of ``"topleft"``, ``"topright"``, ``"bottomleft"``, ``"bottomright"``.
+
+    hide_self : bool, default True
+        Whether to hide the fullscreen button itself after entering fullscreen.
+        Users can exit via the ``Esc`` key.
+
+    locale : str or LocaleConfig, optional
+        Language code (``"en"``, ``"zh"``) or a :class:`LocaleConfig` instance.
+        Defaults to auto-detection, falling back to English.
+
+    Examples
+    --------
+    >>> import folium
+    >>> from foliplus import Fullscreen
+    >>> m = folium.Map()
+    >>> Fullscreen().add_to(m)
+    """
+
+    default_js = [
+        (
+            "Control.Fullscreen.js",
+            f"https://cdn.jsdelivr.net/npm/leaflet.fullscreen@{LEAFLET_FULLSCREEN}/Control.FullScreen.min.js",
+        )
+    ]
+    default_css = [
+        (
+            "Control.FullScreen.css",
+            f"https://cdn.jsdelivr.net/npm/leaflet.fullscreen@{LEAFLET_FULLSCREEN}/Control.FullScreen.css",
+        )
+    ]
+
+    def __init__(
+        self,
+        position: Position = "bottomright",
+        hide_self: bool = True,
+        locale: str | LocaleConfig | None = None,
+    ):
+        super().__init__(position=position, locale=locale)
+        self.hide_self = hide_self
+        self._template = self._get_template(js_file="Fullscreen.js")

foliplus/HeatmapControl.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from ._cdn import CHROMA_JS, H3_JS, SIMPLE_STATISTICS
+from ._typing import Position
+from .base import BaseControl
+from .locale import LocaleConfig
+
+
+class HeatmapControl(BaseControl):
+    """H3 hexbin aggregation heatmap control.
+
+    Auto-discovers point layers (`Marker` / `CircleMarker` / `GeoJSON` Point) and
+    aggregates them into H3 hexagons in real-time via h3-js. Resolution auto-adjusts
+    with zoom.
+
+    Parameters
+    ----------
+    position : str, default "topleft"
+        One of ``"topleft"``, ``"topright"``, ``"bottomleft"``, ``"bottomright"``.
+
+    color_scheme : str, default "Greens"
+        Default color scheme name. Supports chroma.js / ColorBrewer palettes: ``Blues``,
+        ``Greens``, ``Reds``, ``Oranges``, ``Purples``, ``YlOrRd``, ``Viridis``.
+
+    method : Literal["jenks", "quantile", "equal", "heads"], default "jenks"
+        Default classification method.
+
+    n_classes : int, default 6
+        Number of classification classes, range 2-9.
+
+    agg : Literal["count", "sum", "avg", "min", "max"], default "count"
+        Default aggregation method.
+
+    schemes : list[str], optional
+        List of available color scheme names. Can include custom hex values like
+        ``["#f00", "#0f0", "#00f"]``.
+
+    style : dict, optional
+        Grid style overrides. Supported keys:
+        - ``border_weight`` (float, default 1.5): border width
+        - ``border_color`` (str, default "#333333"): border color
+        - ``fill_opacity`` (float, default 0.7): fill opacity
+        - ``border_opacity`` (float, default 0.9): border opacity
+        - ``label_show`` (bool, default True): show aggregated value at hex center
+        - ``label_size`` (int, default 11): label font size
+        - ``label_color`` (str, default "#fff"): label color
+        - ``label_format`` (str, default "auto"): number format —
+          ``"auto"`` (10K/1K suffix), ``"int"``, ``"comma"`` (thousands separator)
+
+    locale : str or LocaleConfig, optional
+        Language code (``"en"``, ``"zh"``) or a :class:`LocaleConfig` instance.
+        Defaults to auto-detection, falling back to English.
+
+    Examples
+    --------
+    >>> import folium
+    >>> from foliplus import HeatmapControl
+    >>> m = folium.Map()
+    >>> HeatmapControl().add_to(m)
+    """
+
+    default_js = [
+        ("h3-js", f"https://cdn.jsdelivr.net/npm/h3-js@{H3_JS}/dist/h3-js.umd.js"),
+        (
+            "simple-statistics",
+            f"https://cdn.jsdelivr.net/npm/simple-statistics@{SIMPLE_STATISTICS}/dist/simple-statistics.min.js",
+        ),
+        (
+            "chroma-js",
+            f"https://cdn.jsdelivr.net/npm/chroma-js@{CHROMA_JS}/chroma.min.js",
+        ),
+    ]
+
+    def __init__(
+        self,
+        position: Position = "topleft",
+        color_scheme: str = "Greens",
+        method: Literal["jenks", "quantile", "equal", "heads"] = "jenks",
+        n_classes: int = 6,
+        agg: Literal["count", "sum", "avg", "min", "max"] = "count",
+        schemes: list[str] | None = None,
+        style: dict | None = None,
+        locale: str | LocaleConfig | None = None,
+    ):
+        super().__init__(position=position, locale=locale)
+        self._template = self._get_template(
+            js_file="HeatmapControl.js", css_file="HeatmapControl.css", use_panel=True
+        )
+        self.color_scheme = color_scheme
+        self.method = method
+        self.n_classes = n_classes
+        self.agg = agg
+        self.schemes = schemes or [
+            "Blues",
+            "Greens",
+            "Reds",
+            "Oranges",
+            "Purples",
+            "YlOrRd",
+            "Viridis",
+        ]
+        self.style = {
+            "border_weight": 1.5,
+            "border_color": "#333333",
+            "fill_opacity": 0.7,
+            "border_opacity": 0.9,
+            "label_show": True,
+            "label_size": 11,
+            "label_color": "#fff",
+            "label_format": "auto",
+        } | (style or {})
+
+        # CDN versions for JS dynamic loader
+        self._h3_version = H3_JS
+        self._ss_version = SIMPLE_STATISTICS
+        self._chroma_version = CHROMA_JS

foliplus/LayerControl.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from collections import OrderedDict
+
+from folium.map import Layer
+
+from ._typing import Position
+from .base import BaseControl
+from .locale import LocaleConfig
+
+
+class LayerControl(BaseControl):
+    """Layer control with geometry-type icons, drag-and-drop order, and a collapsible
+    panel.
+
+    Replaces Folium's default layer control with:
+    - 📐 Geometry-type icons for quick layer identification.
+    - 🔀 Drag-and-drop reordering, synced to Leaflet render order.
+    - ✅ Multi-select checkboxes with z-index stacking.
+    - 🎨 Color picker to replace base maps with a solid background color.
+    - 📂 Collapsible panel consistent with other foliplus controls.
+
+    Parameters
+    ----------
+    position : str, default "topleft"
+        One of ``"topleft"``, ``"topright"``, ``"bottomleft"``, ``"bottomright"``.
+
+    locale : str or LocaleConfig, optional
+        Language code (``"en"``, ``"zh"``) or a :class:`LocaleConfig` instance.
+        Defaults to auto-detection, falling back to English.
+
+    Notes
+    -----
+    Layer identification relies on ``map._layers`` and the ``window`` global variable at
+    runtime. The initial layer list is collected during rendering by traversing the
+    parent map's children.
+
+    Examples
+    --------
+    >>> import folium
+    >>> from foliplus import LayerControl
+    >>> m = folium.Map()
+    >>> LayerControl().add_to(m)
+    """
+
+    def __init__(
+        self,
+        position: Position = "topleft",
+        locale: str | LocaleConfig | None = None,
+    ):
+        super().__init__(position=position, locale=locale)
+        self.base_layers: OrderedDict[str, str] = OrderedDict()
+        self.overlays: OrderedDict[str, str] = OrderedDict()
+        self._template = self._get_template(
+            js_file="LayerControl.js", css_file="LayerControl.css", use_panel=True
+        )
+
+    def render(self, **kwargs):
+        """Collect layers from the parent map before rendering.
+
+        Traverses the parent map's ``_children`` to find ``Layer`` instances, then
+        populates ``self.base_layers`` and ``self.overlays`` according to each layer's
+        ``overlay`` flag.
+        """
+        self.base_layers.clear()
+        self.overlays.clear()
+        for item in self._parent._children.values():
+            if not isinstance(item, Layer) or not item.control:
+                continue
+
+            key = item.layer_name
+            if not item.overlay:
+                self.base_layers[key] = item.get_name()
+            else:
+                self.overlays[key] = item.get_name()
+
+        super().render(**kwargs)

foliplus/MapSearch.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from ._typing import Position
+from .base import BaseControl
+from .locale import LocaleConfig
+
+
+class MapSearch(BaseControl):
+    """Map search control with coordinate and address lookup modes.
+
+    Adds a collapsible search box to the map supporting two modes:
+
+    - 📍 **Coordinate search** (default): enter latitude/longitude to fly to and place a
+      marker.
+    - 🌐 **Address search**: enter a keyword and geocode via Nominatim.
+
+    Switch between modes via the tool button inside the expanded panel.
+
+    Parameters
+    ----------
+    zoom : int, default 15
+        Zoom level after coordinate search. Typically 1-18.
+
+    position : str, default "topleft"
+        One of ``"topleft"``, ``"topright"``, ``"bottomleft"``, ``"bottomright"``.
+
+    locale : str or LocaleConfig, optional
+        Language code (``"en"``, ``"zh"``) or a :class:`LocaleConfig` instance.
+        Defaults to auto-detection, falling back to English.
+
+    Examples
+    --------
+    >>> import folium
+    >>> from foliplus import MapSearch
+    >>> m = folium.Map()
+    >>> MapSearch().add_to(m)
+    """
+
+    def __init__(
+        self,
+        zoom: int = 15,
+        position: Position = "topleft",
+        locale: str | LocaleConfig | None = None,
+    ):
+        super().__init__(position=position, locale=locale)
+        self.zoom = zoom
+        self._template = self._get_template(
+            js_file="MapSearch.js", css_file="MapSearch.css"
+        )

foliplus/MeasureControl.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from ._cdn import GCOORD
+from ._typing import Position
+from .base import BaseControl
+from .locale import LocaleConfig
+
+
+class MeasureControl(BaseControl):
+    """Measurement tools control with locate, distance, and circle drawing modes.
+
+    Click the icon to expand the toolbar, then click a button to activate a mode:
+
+    - 📍 **Locate**: click to place a marker showing coordinates and reverse-geocoded
+      address. Click the popup or the × on the marker to delete it.
+    - 📏 **Distance**: click to draw a polyline. Segment and total distances update
+      in real-time. Double-click / right-click / click the last point to finish.
+    - ⭕ **Circle**: first click sets the center; move the mouse to set the radius;
+      second click confirms.
+    - 🗑️ **Clear**: remove all measurement layers at once.
+
+    After drawing a line or circle: click the object to toggle labels and × buttons;
+    click empty map space to hide × buttons.
+
+    Parameters
+    ----------
+    position : str, default "bottomright"
+        One of ``"topleft"``, ``"topright"``, ``"bottomleft"``, ``"bottomright"``.
+
+    locale : str or LocaleConfig, optional
+        Language code (``"en"``, ``"zh"``) or a :class:`LocaleConfig` instance.
+        Defaults to auto-detection, falling back to English.
+
+    Examples
+    --------
+    >>> import folium
+    >>> from foliplus import MeasureControl
+    >>> m = folium.Map()
+    >>> MeasureControl().add_to(m)
+    """
+
+    default_js = [
+        (
+            "gcoord",
+            f"https://cdn.jsdelivr.net/npm/gcoord@{GCOORD}/dist/gcoord.global.prod.js",
+        ),
+    ]
+
+    def __init__(
+        self,
+        position: Position = "bottomright",
+        locale: str | LocaleConfig | None = None,
+    ):
+        super().__init__(position=position, locale=locale)
+        self._template = self._get_template(
+            js_file="MeasureControl.js", css_file="MeasureControl.css"
+        )

foliplus/ScaleControl.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from ._typing import Position
+from .base import BaseControl
+from .locale import LocaleConfig
+
+
+class ScaleControl(BaseControl):
+    """Scale control with metric units and optional zoom level display.
+
+    Adds a scale bar to the map with an optional current zoom level label.
+
+    Parameters
+    ----------
+    position : str, default "bottomleft"
+        One of ``"topleft"``, ``"topright"``, ``"bottomleft"``, ``"bottomright"``.
+
+    metric : bool, default True
+        Whether to show metric units (meters / kilometers).
+
+    show_zoom : bool, default True
+        Whether to show the current map zoom level.
+
+    locale : str or LocaleConfig, optional
+        Language code (``"en"``, ``"zh"``) or a :class:`LocaleConfig` instance.
+        Defaults to auto-detection, falling back to English.
+
+    Examples
+    --------
+    >>> import folium
+    >>> from foliplus import ScaleControl
+    >>> m = folium.Map()
+    >>> ScaleControl().add_to(m)
+    """
+
+    def __init__(
+        self,
+        position: Position = "bottomleft",
+        metric: bool = True,
+        show_zoom: bool = True,
+        locale: str | LocaleConfig | None = None,
+    ):
+        super().__init__(position=position, locale=locale)
+        self.metric = metric
+        self.show_zoom = show_zoom
+        self._template = self._get_template(
+            js_file="ScaleControl.js", css_file="ScaleControl.css"
+        )

foliplus/__init__.py

@@ -0,0 +1,17 @@
+from .Fullscreen import Fullscreen
+from .HeatmapControl import HeatmapControl
+from .LayerControl import LayerControl
+from .MapSearch import MapSearch
+from .MeasureControl import MeasureControl
+from .ScaleControl import ScaleControl
+
+__all__ = [
+    "Fullscreen",
+    "HeatmapControl",
+    "LayerControl",
+    "MapSearch",
+    "MeasureControl",
+    "ScaleControl",
+]
+
+__version__ = "0.1.0"

foliplus/_cdn.py

@@ -0,0 +1,16 @@
+"""Centralized CDN version management.
+
+All CDN dependency versions are defined here. Bump a version in one place to update it
+across all controls.
+"""
+
+# Fullscreen
+LEAFLET_FULLSCREEN = "3"
+
+# HeatmapControl
+H3_JS = "4"
+SIMPLE_STATISTICS = "7"
+CHROMA_JS = "2"
+
+# MeasureControl
+GCOORD = "1"

foliplus/_typing.py

@@ -0,0 +1,3 @@
+from typing import Literal
+
+Position = Literal["topleft", "topright", "bottomleft", "bottomright"]

foliplus/base.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from pathlib import Path
+from textwrap import dedent
+
+from folium import MacroElement
+from folium.elements import JSCSSMixin
+from jinja2 import Template
+
+from ._cdn import GCOORD
+from ._typing import Position
+from .locale import LocaleConfig, resolve_locale
+
+src_dir = Path(__file__).parent
+js_dir = src_dir / "js"
+css_dir = src_dir / "css"
+
+
+class BaseControl(JSCSSMixin, MacroElement):
+    """Base class for all foliplus controls.
+
+    Handles resource loading (CSS/JS), template injection, and localization. All
+    foliplus components (Fullscreen, HeatmapControl, LayerControl, etc.) inherit from
+    this class.
+
+    Parameters
+    ----------
+    position : str, default "topleft"
+        One of ``"topleft"``, ``"topright"``, ``"bottomleft"``, ``"bottomright"``.
+
+    locale : str or LocaleConfig, optional
+        Language code (``"en"``, ``"zh"``) or a :class:`LocaleConfig` instance.
+        Defaults to auto-detection, falling back to English.
+    """
+
+    _common = css_dir.joinpath("common.css").read_text(encoding="utf-8")
+    _panel = css_dir.joinpath("panel.css").read_text(encoding="utf-8")
+    _runtime = js_dir.joinpath("runtime.js").read_text(encoding="utf-8")
+
+    def __init__(
+        self,
+        position: Position = "topleft",
+        locale: str | LocaleConfig | None = None,
+    ):
+        super().__init__()
+        self._name = self.__class__.__name__
+        self.position = position
+        self.locale = resolve_locale(locale)
+        self._gcoord_version = GCOORD
+
+    def _get_js(self, filename: str) -> str:
+        return js_dir.joinpath(filename).read_text(encoding="utf-8")
+
+    def _get_css(self, filename: str) -> str:
+        return css_dir.joinpath(filename).read_text(encoding="utf-8")
+
+    def _get_template(
+        self,
+        *,
+        js_file: str | None = None,
+        css_file: str | None = None,
+        use_panel: bool = False,
+    ) -> Template:
+        """Build a Jinja2 template with shared CSS/JS + component assets.
+
+        Injects ``common.css``, ``panel.css`` (if ``use_panel=True``), ``runtime.js``,
+        and the specified component JS/CSS files into a Jinja2 macro pair
+        (``html`` / ``script``) for folium's rendering pipeline.
+
+        Parameters
+        ----------
+        js_file : str, optional
+            Component JS filename (e.g. ``"LayerControl.js"``).
+        css_file : str, optional
+            Component CSS filename (e.g. ``"LayerControl.css"``).
+        use_panel : bool, default False
+            Whether to include shared panel CSS.
+
+        Returns
+        -------
+        Template
+            A Jinja2 ``Template`` instance ready for folium rendering.
+        """
+        js_runtime = self._get_js(js_file) if js_file else ""
+        css_common = self._get_css(css_file) if css_file else ""
+        css_panel = self._panel if use_panel else ""
+        locale_table = self.locale.get_js_table()
+
+        return Template(
+            dedent(f"""\
+            {{% macro html(this, kwargs) %}}
+            <style>
+            {self._common}
+            {css_panel}
+            {css_common}
+            </style>
+            {{% endmacro %}}
+
+            {{% macro script(this, kwargs) %}}
+            var _LOCALE = window._LOCALE || {locale_table};
+            {self._runtime}
+            {js_runtime}
+            {{% endmacro %}}""")
+        )