Feat/shapefile map layer source

docs/source/maps/layer_tab.rst

@@ -21,8 +21,8 @@ The layer tab is used to configure the overall layer, including its name and pro
     - **minZoom:** Minimum zoom level (exclusive) for layer visibility.
     - **maxZoom:** Maximum zoom level (inclusive) for layer visibility.
     - **minZoomQuery:** Minimum zoom level (inclusive) at which the layer can be queried. If the map is clicked beyond this zoom, it will zoom in to minZoomQuery.
-    - **clickTolerance:** Pixel tolerance for clicking (and hovering) features. For ``ESRI Image and Map Service`` layers this is the server identify tolerance (default ``10``). For ``GeoJSON`` and ``ESRI Feature Service`` layers it widens the on-screen hit area for clicks and hover popups (default ``0`` — exact hit). When **snapToFeatures** is enabled, this value also sets the snap radius (default ``15``). See `Feature Snapping and Click Tolerance`_ below.
-    - **snapToFeatures:** Snap the cursor to the nearest feature of this layer while hovering, and select that feature on click. Supported for ``ESRI Image and Map Service``, ``GeoJSON``, and ``ESRI Feature Service`` sources. See `Feature Snapping and Click Tolerance`_ below.
+    - **clickTolerance:** Pixel tolerance for clicking (and hovering) features. For ``ESRI Image and Map Service`` layers this is the server identify tolerance (default ``10``). For ``GeoJSON``, ``ESRI Feature Service`` and ``Shapefile`` layers it widens the on-screen hit area for clicks and hover popups (default ``0`` — exact hit). When **snapToFeatures** is enabled, this value also sets the snap radius (default ``15``). See `Feature Snapping and Click Tolerance`_ below.
+    - **snapToFeatures:** Snap the cursor to the nearest feature of this layer while hovering, and select that feature on click. Supported for ``ESRI Image and Map Service``, ``GeoJSON``, ``ESRI Feature Service`` and ``Shapefile`` sources. See `Feature Snapping and Click Tolerance`_ below.
     - **snapSublayer:** For ``ESRI Image and Map Service`` snap layers only — the MapServer sublayer used to load snapping features. Defaults to the first id in the source's ``LAYERS`` ``show:N`` parameter, or ``0``. Set it explicitly when the sublayer you want to snap to differs from that default.
 
 
@@ -47,7 +47,7 @@ Clicking exactly on a thin line or a small point is hard — especially on dense
 
 How snapping behaves:
 
-- **Where the features come from.** ``GeoJSON`` and ``ESRI Feature Service`` layers snap against the features already rendered in the browser — what you see is exactly what you can snap to, with no extra network requests. ``ESRI Image and Map Service`` layers load their features for the current view from the service's ``/query`` endpoint after each pan or zoom (respecting any ``LAYERDEFS`` filter, and the sublayer chosen by **snapSublayer**).
+- **Where the features come from.** ``GeoJSON``, ``ESRI Feature Service`` and ``Shapefile`` layers snap against the features already rendered in the browser — what you see is exactly what you can snap to, with no extra network requests. ``ESRI Image and Map Service`` layers load their features for the current view from the service's ``/query`` endpoint after each pan or zoom (respecting any ``LAYERDEFS`` filter, and the sublayer chosen by **snapSublayer**).
 - **Snapping follows visibility.** A layer only snaps while it is actually drawn: turning the layer off in the layer control, or moving outside its **minZoom** / **maxZoom** / **minResolution** / **maxResolution** bounds, disables snapping immediately.
 - **minZoomQuery applies.** Like popup queries, snapping is inactive below the layer's **minZoomQuery** zoom level.
 - **Radius.** The hover snap radius is **clickTolerance** when set, otherwise ``15`` pixels. The confluence gather radius is at least ``35`` pixels and never narrower than the snap radius.

docs/source/maps/source_tab.rst

@@ -96,6 +96,42 @@ The GeoJSON source is different from the other options. It provides a text area
 
 ------------------------------------------------------------------------------------------------------------------------
 
++++++++++
+Shapefile
++++++++++
+
+
+The Shapefile source draws an ESRI Shapefile that is already published on the web. The browser fetches and reads it directly — nothing is uploaded to TethysDash, and the saved layer keeps only the URL, so the file stays wherever it already lives and stays current when it is replaced there.
+
+Two forms are accepted, and the same **url** field takes either:
+
+- A **zipped shapefile**, whose path ends in ``.zip``.
+- The **.shp component** of an unzipped set. The sibling ``.dbf``, ``.prj`` and ``.cpg`` files are requested from the same path automatically, so only the ``.shp`` URL is entered. The ``.shx`` index is not requested -- it is not needed to draw the layer. Any query string on the URL is preserved on each request, which keeps signed links working.
+
+A portal **download endpoint** counts as the first form even when its path carries no ``.zip`` — ArcGIS Hub and similar services serve shapefiles from a URL ending in something like ``/downloads/data?format=shp``. Paste it as-is.
+
+    - **url:** *(required)* URL of a zipped shapefile, or of its ``.shp`` component. Must be ``http`` or ``https``.
+    - **projection:** *(optional)* Used only when the shapefile carries no ``.prj``. Accepts a code such as ``EPSG:5070``, or a full WKT or proj4 definition for a coordinate system the map does not already know.
+    - **attributions:** *(optional)* Attribution text for the layer.
+
+The coordinate system comes from the shapefile's own ``.prj`` and does not need to be entered. If the file has no ``.prj``, the **projection** property is used instead; if neither is present the layer reports that its coordinates cannot be placed rather than guessing at them.
+
+Attribute values come from the ``.dbf``. If that component is missing, the geometry still draws but the layer offers no fields for style rules or popups.
+
+**Attribute text.** The character encoding comes from the ``.cpg`` component when the shapefile has one. When it does not, UTF-8 is detected from the attribute bytes themselves, and anything that is not valid UTF-8 is read as Windows-1252. Values whose padding is unusual — some publishers pad with null bytes rather than spaces — are trimmed either way, so a field that is empty in the source reads as empty rather than as padding characters.
+
+Styling, popups, attribute variables and snapping all behave as they do for a :ref:`GeoJSON <source_tab>` layer — see the :ref:`style_tab` and :ref:`attributes_and_popups_tab`.
+
+**Reading the fields.** The Style and Attributes tabs need the ``.dbf`` field names, which means reading the source. Because that can be a large download, it happens when you ask for it: use **Read shapefile fields** on this tab. One read serves both tabs. If the saved style rules, popup settings or attribute variables name a field the source no longer has — after the file is republished with a renamed column, for instance — the field is listed so the affected rules can be corrected. Those rules will not match anything until then, and the layer will still draw.
+
+**Size limit.** A shapefile is read in one piece, so the components are limited to 25 MB once decompressed. An archive that declares an oversized component is refused before that component is expanded; one that under-declares is refused as soon as the extra bytes arrive, so the declared size cannot be used to get past the limit. Either way the message states both the observed and the permitted size. Clip or simplify the data, or serve a reduced copy.
+
+.. note::
+
+    The browser must be allowed to fetch the file, which means the host has to send permissive `CORS <https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS>`_ headers. Most agency open-data portals do — ArcGIS Hub and AWS-hosted government buckets among them — but some widely used sources do not. Census TIGER files, for example, cannot be read from a browser at all. When a fetch is refused, the layer says so and suggests converting the shapefile to GeoJSON and using the :ref:`GeoJSON <source_tab>` source instead, which stores the data with the dashboard rather than fetching it.
+
+------------------------------------------------------------------------------------------------------------------------
+
 +++++++++++
 Vector Tile
 +++++++++++

docs/source/maps/style_tab.rst

@@ -6,7 +6,7 @@ Style Tab
 
 
 
-The style tab lets you apply custom styles to map layers. Custom styling is available for GeoJSON, ESRI Feature Service, and PMTiles Vector layers. Two types of styling are supported:
+The style tab lets you apply custom styles to map layers. Custom styling is available for GeoJSON, ESRI Feature Service, PMTiles Vector, and Shapefile layers. Two types of styling are supported:
 
 **MapLibre Styling**: Follows the `MapLibre Style Spec <https://maplibre.org/maplibre-style-spec/>`_ and uses the `ol-mapbox-style applyStyle <https://openlayers.org/ol-mapbox-style/functions/applyStyle.html>`_ function. Refer to these resources to ensure your layers render correctly.
 

docs/source/plugins.rst

@@ -995,8 +995,8 @@ from the plugin
             - **minZoom** (optional): The minimum view zoom level (exclusive) above which this layer will be visible.
             - **maxZoom** (optional): The maximum view zoom level (inclusive) at which this layer will be visible.
             - **minZoomQuery** (optional): The minimum view zoom level (inclusive) at which this layer can be queried. If the mp is clicked beyond the zoom level, then the map will zoom into the minZoomQuery value.
-            - **clickTolerance** (optional): Pixel tolerance for clicking and hovering features. For "ESRI Image and Map Service" sources this is the server identify tolerance (default 10); for "GeoJSON" and "ESRI Feature Service" sources it widens the on-screen hit area (default 0). Also sets the snap radius when snapToFeatures is enabled (default 15). See maps :ref:`feature_snapping` for details.
-            - **snapToFeatures** (optional): A boolean. When true, the cursor snaps to the nearest feature of this layer on hover and a click selects that feature directly. Supported for "ESRI Image and Map Service", "GeoJSON", and "ESRI Feature Service" sources. See maps :ref:`feature_snapping` for details.
+            - **clickTolerance** (optional): Pixel tolerance for clicking and hovering features. For "ESRI Image and Map Service" sources this is the server identify tolerance (default 10); for "GeoJSON", "ESRI Feature Service" and "Shapefile" sources it widens the on-screen hit area (default 0). Also sets the snap radius when snapToFeatures is enabled (default 15). See maps :ref:`feature_snapping` for details.
+            - **snapToFeatures** (optional): A boolean. When true, the cursor snaps to the nearest feature of this layer on hover and a click selects that feature directly. Supported for "ESRI Image and Map Service", "GeoJSON", "ESRI Feature Service" and "Shapefile" sources. See maps :ref:`feature_snapping` for details.
             - **snapSublayer** (optional): For "ESRI Image and Map Service" snap layers — the MapServer sublayer used to load snapping features. Defaults to the first id in the source's LAYERS "show:N" parameter, else 0.
         - **layerVisibility** (optional): A boolean indicating the default visibility of the layer. 
         - **style** (required): An object that contains the metadata for styling. See maps :ref:`style_tab` for more information.
@@ -1022,6 +1022,10 @@ from the plugin
     - ``Vector Tile``
     - ``PMTiles Vector``
     - ``PMTiles Raster``
+    - ``Shapefile``
+    - ``GeoTIFF``
+    - ``Zarr``
+    - ``Static Image``
 
     **Builder methods:**