Metadata-Version: 2.4
Name: foliplus
Version: 0.4.0
Summary: foliplus: the missing piece between "see the map" and "use the map". GeoPandas handles data, Folium renders it, foliplus brings it to life.
Author-email: "40% <@Zeroto521>" <Zeroto521@gmail.com>
License-Expression: MIT
Project-URL: Documentation, https://foliplus.readthedocs.io
Project-URL: Source, https://github.com/Zeroto521/foliplus
Project-URL: Issues, https://github.com/Zeroto521/foliplus/issues
Keywords: folium,leaflet,gis,map,visualization
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: folium>=0.14.0
Dynamic: license-file

<h1 align="center">
  <a href="https://foliplus.readthedocs.io">foliplus</a>
</h1>

<p align="center">
  <a href="https://foliplus.readthedocs.io/en/latest/quickstart.html#display-map"><img src="https://raw.githubusercontent.com/Zeroto521/foliplus/main/doc/source/_static/preview.png" alt="Preview"></a>
</p>

<p align="center">
  <em>foliplus: the missing piece between "see the map" and "use the map". GeoPandas handles data, Folium renders it, foliplus brings it to life.</em>
</p>

<p align="center">
  <a href="https://pypi.org/project/foliplus">
    <img src="https://img.shields.io/pypi/v/foliplus?color=%2334D058" alt="Package Version">
  </a>
  <a href="https://pypi.org/project/foliplus">
    <img src="https://img.shields.io/pypi/pyversions/foliplus.svg?color=%2334D058" alt="Supported Python">
  </a>
  <a href="https://github.com/Zeroto521/foliplus/actions/workflows/test.yaml">
    <img src="https://github.com/Zeroto521/foliplus/actions/workflows/test.yaml/badge.svg" alt="Tests">
  </a>
  <a href="https://codecov.io/gh/Zeroto521/foliplus">
    <img src="https://codecov.io/gh/Zeroto521/foliplus/branch/main/graph/badge.svg" alt="Codecov">
  </a>
  <a href="https://foliplus.readthedocs.io/en/latest/?badge=latest">
    <img src="https://readthedocs.org/projects/foliplus/badge/?version=latest" alt="Documentation">
  </a>
</p>

## Scope

Layer data passed to foliplus is read-only: no editing, upload, or deletion.

Data processing happens upstream. foliplus handles the map, not the data.

## Features

| Control                 | Description                                                                            |
| :---------------------- | :------------------------------------------------------------------------------------- |
| 📷 **ExportControl**     | Capture a specific area of the map and export it as an image.                          |
| 🖥️ **FullscreenControl** | Fullscreen toggle with auto-hide for other controls.                                   |
| 🔥 **HeatmapControl**    | H3 hexbin heatmap with zoom-adaptive resolution and labeled hexagons.                  |
| 🗂️ **LayerControl**      | Layer panel to organize, inspect, and zoom to map layers.                              |
| 🎯 **LocateControl**     | Fly to the user's current position.                                                    |
| 📏 **MeasureControl**    | Measure distances, areas, and circles; place geocoded markers; then edit by dragging nodes. |
| 📐 **ScaleControl**      | Scale bar with metric units and optional zoom level display.                           |
| 🔍 **SearchControl**     | Coordinate and address search via pluggable geocode providers.                        |

## Beyond Plugins

Traditional map component libraries treat each tool as an independent plugin. foliplus
was designed as one **system** from the start:

- Components **communicate** with each other, instead of working in isolation
- Layers are **managed centrally**, instead of each tool owning its own stack
- Conflicts are **resolved automatically**, instead of tools interfering with each other
- Third-party components can **plug into** the system, instead of being locked out

## Built-in Coordination

Layer-producing tools register their canvas or layer through **LayerControl**,
which manages z-order, visibility, and lifecycle centrally.
This means they share a single layer stack — no z-index clashes, no orphaned DOM
elements.

On top of this shared layer foundation, tools coordinate further:

- While **measuring**, search and locate are blocked to prevent map interaction conflicts
- During **export**, measurement pauses, heatmap renders in full resolution, and layer
  order is synced for a complete screenshot
- When a layer is **removed** from the layer panel, the component that owns it
  (e.g. measurement) auto-cleans its state
- When layers change, the heatmap refreshes automatically

All of this happens without manual wiring — foliplus handles it internally.

## Compatibility

Requires `folium>=0.14.0`. Leaflet is not a Python dependency — the TypeScript controls run against the Leaflet Folium injects into the page.

CI runs the full suite on Folium's Leaflet (1.9.3) and a bring-up smoke on Leaflet 1.0.0 for pages that load a different pin.
