@lad-sapienza/scms-core 0.1.0-alpha.7 → 0.1.0-alpha.9

package/README.md

@@ -64,7 +64,7 @@ import BSNavbar from '@lad-sapienza/scms-core/components/BSNavbar';
 import { directusLoader } from '@lad-sapienza/scms-core/integrations/directusLoader';
 ```
 
-See each component folder's own `README.md` (`components/DataTb`, `components/Gallery`, `components/RedirectPage`, `components/ZoteroGeoViewer`, `components/`) for detailed API docs and examples.
+See each component folder's own `README.md` (`components/DataTb`, `components/Gallery`, `components/Map`, `components/RedirectPage`, `components/ZoteroGeoViewer`, `components/`) for detailed API docs and examples.
 
 ## Creating a new site
 

package/components/Map/LayerControl.tsx

@@ -3,7 +3,7 @@ import { createRoot, type Root } from 'react-dom/client';
 import { createPortal } from 'react-dom';
 import { Layers, Search, X } from 'lucide-react';
 import type { IControl } from 'maplibre-gl';
-import type { BaseLayerConfig, VectorLayerConfig, ControlPosition, SearchInFields, SearchQuery } from './types';
+import type { BaseLayerConfig, OverlayLayerConfig, ControlPosition, SearchInFields, SearchQuery } from './types';
 import { SearchUI } from './Search';
 import { useTranslation } from '../i18n';
 
@@ -11,22 +11,22 @@ export interface LayerControlProps {
   baseLayers?: BaseLayerConfig[];
   activeBaseLayer?: number;
   onBaseLayerChange?: (index: number) => void;
-  vectorLayers?: Array<VectorLayerConfig & { id: string }>;
-  vectorLayerVisibility?: Record<string, boolean>;
-  onVectorLayerToggle?: (layerId: string) => void;
+  overlayLayers?: Array<OverlayLayerConfig & { id: string }>;
+  overlayLayerVisibility?: Record<string, boolean>;
+  onOverlayLayerToggle?: (layerId: string) => void;
   onLayerSearch?: (layerId: string, query: SearchQuery) => void;
   layerSearchQueries?: Record<string, SearchQuery>;
   position?: ControlPosition;
 }
 
 // Internal React component for the control UI
-function LayerControlUI({ 
-  baseLayers = [], 
-  activeBaseLayer = 0, 
+function LayerControlUI({
+  baseLayers = [],
+  activeBaseLayer = 0,
   onBaseLayerChange,
-  vectorLayers = [],
-  vectorLayerVisibility = {},
-  onVectorLayerToggle,
+  overlayLayers = [],
+  overlayLayerVisibility = {},
+  onOverlayLayerToggle,
   onLayerSearch,
   layerSearchQueries = {},
 }: Omit<LayerControlProps, 'position'>) {
@@ -36,7 +36,7 @@ function LayerControlUI({
   const radioGroupId = React.useId();
   const timeoutRef = React.useRef<NodeJS.Timeout | null>(null);
 
-  const hasContent = baseLayers.length > 0 || vectorLayers.length > 0;
+  const hasContent = baseLayers.length > 0 || overlayLayers.length > 0;
   if (!hasContent) return null;
 
   const handleMouseEnter = () => {
@@ -150,20 +150,20 @@ function LayerControlUI({
           whiteSpace: 'nowrap'
         }}>
           
-          {/* Vector Layers Section */}
-          {vectorLayers.length > 0 && (
+          {/* Overlay Layers Section */}
+          {overlayLayers.length > 0 && (
             <div style={{ marginBottom: 10 }}>
-              {vectorLayers.map((layer) => (
+              {overlayLayers.map((layer) => (
                 <div key={layer.id} style={{ marginBottom: 6, display: 'flex', alignItems: 'center' }}>
                   <input
                     type="checkbox"
-                    id={`vector-layer-${layer.id}`}
-                    checked={vectorLayerVisibility[layer.id] !== false}
-                    onChange={() => onVectorLayerToggle?.(layer.id)}
+                    id={`overlay-layer-${layer.id}`}
+                    checked={overlayLayerVisibility[layer.id] !== false}
+                    onChange={() => onOverlayLayerToggle?.(layer.id)}
                     style={{ marginRight: 8, cursor: 'pointer' }}
                   />
-                  <label 
-                    htmlFor={`vector-layer-${layer.id}`}
+                  <label
+                    htmlFor={`overlay-layer-${layer.id}`}
                     style={{ cursor: 'pointer', fontSize: '12px', userSelect: 'none', flex: 1 }}
                   >
                     {layer.name}
@@ -321,7 +321,7 @@ export class LayerControlClass implements IControl {
     // Compare props to avoid unnecessary re-renders
     const hasChanged = 
       JSON.stringify(this.props.layerSearchQueries) !== JSON.stringify(newProps.layerSearchQueries) ||
-      JSON.stringify(this.props.vectorLayerVisibility) !== JSON.stringify(newProps.vectorLayerVisibility) ||
+      JSON.stringify(this.props.overlayLayerVisibility) !== JSON.stringify(newProps.overlayLayerVisibility) ||
       this.props.activeBaseLayer !== newProps.activeBaseLayer;
 
     if (hasChanged) {
@@ -354,7 +354,7 @@ export function LayerControl(props: LayerControlProps) {
       }
     }
     previousPropsRef.current = props;
-  }, [props.layerSearchQueries, props.vectorLayerVisibility, props.activeBaseLayer]);
+  }, [props.layerSearchQueries, props.overlayLayerVisibility, props.activeBaseLayer]);
 
   // Create control instance only once
   if (!controlRef.current) {

package/components/Map/Map.tsx

@@ -10,14 +10,15 @@ import MapLibreMap, {
   type MapRef
 } from '@vis.gl/react-maplibre';
 import 'maplibre-gl/dist/maplibre-gl.css';
-import type { MapProps, VectorLayerConfig } from './types';
+import type { MapProps, OverlayLayerConfig } from './types';
 import { RasterLayerLibre } from './RasterLayerLibre';
 import { LayerControlIControl } from './LayerControl';
 import { directusShorthandToConfig } from '../../utils/directus-config';
 import type { BaseLayerConfig } from './types';
 import { defaultBasemaps, getBasemap } from './defaultBasemaps';
 import { fetchData } from '../../utils/data-fetcher';
-import { dataToGeoJson, parseStringTemplate, filterObjectToPredicate, searchQueryToMapLibreFilter, searchQueryToPredicate } from './utils';
+import type { SourceConfig } from '../../utils/data-fetcher';
+import { dataToGeoJson, parseStringTemplate, filterObjectToPredicate, searchQueryToMapLibreFilter, searchQueryToPredicate, expandXyzSubdomains, buildWmsUrl } from './utils';
 import { useTranslation } from '../i18n';
 import type { FeatureCollection } from 'geojson';
 import type { CircleLayerSpecification } from 'maplibre-gl';
@@ -26,13 +27,32 @@ import type { SearchQuery } from './types';
 // Default base layer (OSM)
 const DEFAULT_BASE_LAYERS: BaseLayerConfig[] = [defaultBasemaps.OSM];
 
+// Stable identity for the "no explicit overlayLayers prop" case. A literal
+// `overlayLayers = []` default in the destructure below allocates a fresh
+// array on every render whenever the caller uses only a shorthand prop
+// (`geojson` / `csv` / `json` / `directus`) and omits `overlayLayers`. That
+// fresh array is a dependency of the `allOverlayLayers` useMemo, so the memo
+// recomputes every render → the data-loading effect keyed on it re-runs →
+// `setLayersData` → re-render → loop ("Maximum update depth exceeded", plus a
+// `fitToContent` fitBounds animation that restarts forever). Hoisting the
+// empty array to a module constant (same pattern as DEFAULT_BASE_LAYERS)
+// keeps its reference stable across renders.
+const EMPTY_OVERLAY_LAYERS: OverlayLayerConfig[] = [];
+
+// Vector-tile, xyz and wms sources are rendered natively/via RasterLayerLibre
+// and never go through fetchData — this narrows the union so TS knows
+// `layer.source` is a plain SourceConfig wherever this guard is used.
+function isFetchableLayer(layer: OverlayLayerConfig): layer is OverlayLayerConfig & { source: SourceConfig } {
+  return layer.source.type !== 'vector' && layer.source.type !== 'xyz' && layer.source.type !== 'wms';
+}
+
 export function Map({
   height = '600px',
   center = '0,0,2',
   mapStyle,
   styleOverrides,
   baseLayers = DEFAULT_BASE_LAYERS,
-  vectorLayers = [],
+  overlayLayers = EMPTY_OVERLAY_LAYERS,
   geolocateControl,
   fullscreenControl,
   navigationControl = 'top-left',
@@ -48,15 +68,15 @@ export function Map({
   const [activeBaseLayer, setActiveBaseLayer] = useState<number>(0);
   const [layersData, setLayersData] = useState<Record<string, FeatureCollection>>({});
   const [hoveredFeature, setHoveredFeature] = useState<any>(null);
-  const [vectorLayerVisibility, setVectorLayerVisibility] = useState<Record<string, boolean>>({});
+  const [overlayLayerVisibility, setOverlayLayerVisibility] = useState<Record<string, boolean>>({});
   const [mapLoaded, setMapLoaded] = useState(false);
   const mapRef = useRef<MapRef>(null);
-  const loadedLayers = useRef<Set<string>>(new Set());
+  const rawSourceCache = useRef<globalThis.Map<string, FeatureCollection>>(new globalThis.Map());
   const layerControlRef = useRef<LayerControlIControl | null>(null);
   const [parsedStyleLayers, setParsedStyleLayers] = useState<{
     baseLayers: BaseLayerConfig[];
-    vectorLayers: VectorLayerConfig[];
-  }>({ baseLayers: [], vectorLayers: [] });
+    overlayLayers: OverlayLayerConfig[];
+  }>({ baseLayers: [], overlayLayers: [] });
   const [mergedMapStyle, setMergedMapStyle] = useState<any>(null);
   const [layerExpansions, setLayerExpansions] = useState<Record<string, {
     popupTemplate?: string;
@@ -67,7 +87,7 @@ export function Map({
   // Parse mapStyle JSON to extract layers and apply overrides
   useEffect(() => {
     if (!mapStyle) {
-      setParsedStyleLayers({ baseLayers: [], vectorLayers: [] });
+      setParsedStyleLayers({ baseLayers: [], overlayLayers: [] });
       setMergedMapStyle(null);
       setLayerExpansions({});
       return;
@@ -86,7 +106,7 @@ export function Map({
         }
 
         const baseLayers: BaseLayerConfig[] = [];
-        const vectorLayers: VectorLayerConfig[] = [];
+        const overlayLayers: OverlayLayerConfig[] = [];
         const expansions: Record<string, any> = {};
 
         // Apply styleOverrides to layers
@@ -148,7 +168,7 @@ export function Map({
               const source = styleObj.sources[layer.source];
               if (source && source.type === 'vector') {
                 const expansion = expansions[layer.id] || {};
-                vectorLayers.push({
+                overlayLayers.push({
                   name: layer.metadata?.label || layer.id,
                   source: {
                     type: 'vector',
@@ -164,11 +184,11 @@ export function Map({
           });
         }
 
-        setParsedStyleLayers({ baseLayers, vectorLayers });
+        setParsedStyleLayers({ baseLayers, overlayLayers });
         setMergedMapStyle(styleObj);
       } catch (error) {
         console.error('Failed to parse mapStyle:', error);
-        setParsedStyleLayers({ baseLayers: [], vectorLayers: [] });
+        setParsedStyleLayers({ baseLayers: [], overlayLayers: [] });
         setMergedMapStyle(null);
         setLayerExpansions({});
       }
@@ -234,13 +254,13 @@ export function Map({
     return null;
   }, [geojson, csv, json, directus]);
 
-  // Combine explicit vectorLayers with implicit source
-  const allVectorLayers = useMemo(() => {
-    let layers = [...vectorLayers];
-    
+  // Combine explicit overlayLayers with implicit source
+  const allOverlayLayers = useMemo(() => {
+    let layers = [...overlayLayers];
+
     // If using mapStyle, add parsed vector layers from style JSON
-    if (mapStyle && parsedStyleLayers.vectorLayers.length > 0) {
-      layers = [...parsedStyleLayers.vectorLayers, ...layers];
+    if (mapStyle && parsedStyleLayers.overlayLayers.length > 0) {
+      layers = [...parsedStyleLayers.overlayLayers, ...layers];
     }
     
     if (implicitSource) {
@@ -288,28 +308,28 @@ export function Map({
       layers.push(layerConfig);
     }
     return layers;
-  }, [vectorLayers, implicitSource, geojson, csv, mapStyle, parsedStyleLayers.vectorLayers]);
+  }, [overlayLayers, implicitSource, geojson, csv, mapStyle, parsedStyleLayers.overlayLayers]);
 
   // Initialize and update visibility when layers change
   useEffect(() => {
-    setVectorLayerVisibility(prev => {
+    setOverlayLayerVisibility(prev => {
       const newVisibility: Record<string, boolean> = { ...prev };
       let hasChanges = false;
-      
-      allVectorLayers.forEach(layer => {
+
+      allOverlayLayers.forEach(layer => {
         const layerId = `layer-${layer.name.replace(/\s+/g, '-')}`;
-        
+
         if (newVisibility[layerId] === undefined) {
           newVisibility[layerId] = layer.visible !== false;
           hasChanges = true;
         }
       });
-      
+
       return hasChanges ? newVisibility : prev;
     });
-  }, [allVectorLayers]);
+  }, [allOverlayLayers]);
 
-  // Handle vector layer visibility toggle
+  // Handle overlay layer visibility toggle
   //
   // Wrapped in useCallback (both here and below) so its identity stays
   // stable across renders — it's one of two functions passed into the
@@ -324,14 +344,14 @@ export function Map({
   // created (correct) control was the one actually getting removed a tick
   // later, leaving the stale first control (still showing the original
   // basemap selected) as the only one left on the map.
-  const handleVectorLayerToggle = useCallback((layerId: string) => {
-    setVectorLayerVisibility(prev => ({
+  const handleOverlayLayerToggle = useCallback((layerId: string) => {
+    setOverlayLayerVisibility(prev => ({
       ...prev,
       [layerId]: !prev[layerId]
     }));
   }, []);
 
-  // Handle search for vector layers — see handleVectorLayerToggle above.
+  // Handle search for overlay layers — see handleOverlayLayerToggle above.
   const handleLayerSearch = useCallback((layerId: string, query: SearchQuery) => {
     setLayerSearchQueries(prev => ({
       ...prev,
@@ -339,71 +359,68 @@ export function Map({
     }));
   }, []);
 
-  // Load data for all vector layers
+  // Load data for all fetchable overlay layers (vector-tile, xyz and wms
+  // sources are rendered natively/via RasterLayerLibre and never reach
+  // fetchData). Raw fetched+converted GeoJSON is cached per unique source
+  // (rawSourceCache, keyed by JSON.stringify(source)) so N layer entries
+  // sharing the same source — differing only in filter/style — fetch once;
+  // each layer's own filter is applied on top of the cached raw data.
+  // Loading no longer depends on `visible`: visibility only controls
+  // display (see the render below), not whether data is ever fetched —
+  // otherwise a layer started as visible:false could never be loaded even
+  // after the user later checks it on, since this effect only re-runs when
+  // allOverlayLayers itself changes, not on a visibility toggle.
   useEffect(() => {
     const loadAllLayers = async () => {
-      const newLayersData: Record<string, FeatureCollection> = {};
-      const layersToLoad: typeof allVectorLayers = [];
-      
-      // Check which layers need to be loaded
-      for (const layer of allVectorLayers) {
-        // Vector-tile sources (parsed from a mapStyle JSON) are rendered
-        // natively by MapLibre from the style's own tiles/sources — they
-        // aren't rows to fetch, so skip them here to avoid a spurious
-        // "unsupported source type" error on every load.
-        if (layer.source.type === 'vector') continue;
+      const fetchableLayers = allOverlayLayers.filter(isFetchableLayer);
+      if (fetchableLayers.length === 0) return;
 
+      const seen = new Set<string>();
+      for (const layer of fetchableLayers) {
         const layerKey = JSON.stringify(layer.source);
-        if (!loadedLayers.current.has(layerKey) && layer.visible !== false) {
-          layersToLoad.push(layer);
-        }
-      }
-      
-      // Only proceed if there are new layers to load
-      if (layersToLoad.length === 0) return;
-      
-      for (const layer of layersToLoad) {
+        if (rawSourceCache.current.has(layerKey) || seen.has(layerKey)) continue;
+        seen.add(layerKey);
+
         try {
           const data = await fetchData(layer.source);
-          
+
           // Extract custom column names from CSV source if provided
           const customLng = layer.source.type === 'csv' ? layer.source.lng : undefined;
           const customLat = layer.source.type === 'csv' ? layer.source.lat : undefined;
-          
+
           // Extract geoField from Directus source if provided
           const geoField = layer.source.type === 'directus' ? layer.source.geoField : undefined;
-          
-          let geoJson = dataToGeoJson(data, customLng, customLat, geoField);
-          
-          // Apply client-side filter if provided
-          if (layer.filter && typeof layer.filter === 'function') {
-            geoJson = {
-              ...geoJson,
-              features: geoJson.features.filter(layer.filter)
-            };
-          }
-          
-          newLayersData[layer.name] = geoJson;
-          
-          // Mark this layer as loaded
-          const layerKey = JSON.stringify(layer.source);
-          loadedLayers.current.add(layerKey);
+
+          const geoJson = dataToGeoJson(data, customLng, customLat, geoField);
+          rawSourceCache.current.set(layerKey, geoJson);
         } catch (err) {
           console.error(`Failed to load layer "${layer.name}":`, err);
           // Continue loading other layers even if one fails
         }
       }
-      
-      // Only update state if we actually loaded new data
+
+      // Project cached raw data into each layer's own (filtered) view —
+      // cheap client-side work, no network, safe to redo whenever
+      // allOverlayLayers changes (e.g. a filter edit).
+      const newLayersData: Record<string, FeatureCollection> = {};
+      for (const layer of fetchableLayers) {
+        const raw = rawSourceCache.current.get(JSON.stringify(layer.source));
+        if (!raw) continue; // fetch failed for this source
+
+        newLayersData[layer.name] = layer.filter && typeof layer.filter === 'function'
+          ? { ...raw, features: raw.features.filter(layer.filter) }
+          : raw;
+      }
+
       if (Object.keys(newLayersData).length > 0) {
         setLayersData(prev => ({ ...prev, ...newLayersData }));
       }
     };
-    
-    if (allVectorLayers.length > 0 && typeof window !== 'undefined') {
+
+    if (allOverlayLayers.length > 0 && typeof window !== 'undefined') {
       loadAllLayers();
     }
-  }, [allVectorLayers]);
+  }, [allOverlayLayers]);
 
   // Handle fitToContent separately when map is loaded and data is ready
   useEffect(() => {
@@ -411,7 +428,7 @@ export function Map({
     if (!map || !mapLoaded || Object.keys(layersData).length === 0) return;
 
     // Find first layer with fitToContent
-    const layerToFit = allVectorLayers.find(layer => 
+    const layerToFit = allOverlayLayers.find(layer =>
       layer.fitToContent && layersData[layer.name] && layersData[layer.name].features.length > 0
     );
 
@@ -449,30 +466,30 @@ export function Map({
         map.fitBounds(bounds, { padding: 50, duration: 1000 });
       }
     }, 100);
-  }, [mapLoaded, layersData, allVectorLayers]);
+  }, [mapLoaded, layersData, allOverlayLayers]);
 
   // Add LayerControl as a proper IControl
   useEffect(() => {
     const map = mapRef.current?.getMap();
     if (!map || !mapLoaded || !layerControl) return;
-    
-    // Show layer control if we have base layers or vector layers
-    const hasLayers = resolvedBaseLayers.length > 0 || allVectorLayers.length > 0;
+
+    // Show layer control if we have base layers or overlay layers
+    const hasLayers = resolvedBaseLayers.length > 0 || allOverlayLayers.length > 0;
     if (!hasLayers) return;
 
     const position = typeof layerControl === 'string' ? layerControl : 'top-right';
-    
+
     // Create and add control
     const control = new LayerControlIControl({
       baseLayers: resolvedBaseLayers,
       activeBaseLayer,
       onBaseLayerChange: setActiveBaseLayer,
-      vectorLayers: allVectorLayers.map(layer => ({
+      overlayLayers: allOverlayLayers.map(layer => ({
         ...layer,
         id: `layer-${layer.name.replace(/\s+/g, '-')}`
       })),
-      vectorLayerVisibility,
-      onVectorLayerToggle: handleVectorLayerToggle,
+      overlayLayerVisibility,
+      onOverlayLayerToggle: handleOverlayLayerToggle,
       onLayerSearch: handleLayerSearch,
       layerSearchQueries
     });
@@ -490,7 +507,7 @@ export function Map({
         map.removeControl(control);
       }, 0);
     };
-  }, [mapLoaded, layerControl, resolvedBaseLayers, allVectorLayers.length, handleLayerSearch]);
+  }, [mapLoaded, layerControl, resolvedBaseLayers, allOverlayLayers.length, handleLayerSearch]);
 
   // Update layer control props when they change
   useEffect(() => {
@@ -499,17 +516,17 @@ export function Map({
         baseLayers: resolvedBaseLayers,
         activeBaseLayer,
         onBaseLayerChange: setActiveBaseLayer,
-        vectorLayers: allVectorLayers.map(layer => ({
+        overlayLayers: allOverlayLayers.map(layer => ({
           ...layer,
           id: `layer-${layer.name.replace(/\s+/g, '-')}`
         })),
-        vectorLayerVisibility,
-        onVectorLayerToggle: handleVectorLayerToggle,
+        overlayLayerVisibility,
+        onOverlayLayerToggle: handleOverlayLayerToggle,
         onLayerSearch: handleLayerSearch,
         layerSearchQueries
       });
     }
-  }, [resolvedBaseLayers, activeBaseLayer, allVectorLayers, vectorLayerVisibility, handleLayerSearch, layerSearchQueries]);
+  }, [resolvedBaseLayers, activeBaseLayer, allOverlayLayers, overlayLayerVisibility, handleLayerSearch, layerSearchQueries]);
 
   // Control visibility of layers from style JSON
   useEffect(() => {
@@ -517,10 +534,10 @@ export function Map({
     if (!map || !mapLoaded || !mapStyle) return;
 
     // Update visibility for vector layers from parsed style
-    parsedStyleLayers.vectorLayers.forEach(layer => {
+    parsedStyleLayers.overlayLayers.forEach(layer => {
       const layerId = `layer-${layer.name.replace(/\s+/g, '-')}`;
-      const isVisible = vectorLayerVisibility[layerId] !== false;
-      
+      const isVisible = overlayLayerVisibility[layerId] !== false;
+
       // The original layer ID from the style JSON
       const styleLayerId = layer.style?.id;
       if (styleLayerId && map.getLayer(styleLayerId)) {
@@ -531,7 +548,7 @@ export function Map({
         );
       }
     });
-  }, [vectorLayerVisibility, mapLoaded, mapStyle, parsedStyleLayers.vectorLayers]);
+  }, [overlayLayerVisibility, mapLoaded, mapStyle, parsedStyleLayers.overlayLayers]);
 
   // Handle fitToContent for layers with expansions
   useEffect(() => {
@@ -604,8 +621,8 @@ export function Map({
           if (e.features && e.features.length > 0) {
             const clickedLayerId = e.features[0].layer?.id;
             
-            // Check for popup in allVectorLayers (includes parsed style layers)
-            const layerConfig = allVectorLayers.find(l => {
+            // Check for popup in allOverlayLayers (includes parsed style layers)
+            const layerConfig = allOverlayLayers.find(l => {
               const layerId = `layer-${l.name.replace(/\s+/g, '-')}`;
               return layerId === clickedLayerId;
             });
@@ -624,30 +641,50 @@ export function Map({
           }
         }}
         interactiveLayerIds={[
-          ...allVectorLayers.map(l => `layer-${l.name.replace(/\s+/g, '-')}`),
+          ...allOverlayLayers.map(l => `layer-${l.name.replace(/\s+/g, '-')}`),
           ...Object.keys(layerExpansions) // Add layer IDs that have expansions
         ]}
       >
         {/* Base Layers (only if no full mapStyle is provided) - render ALL but control visibility */}
         {!mapStyle && resolvedBaseLayers.map((layer, index) => (
-          <RasterLayerLibre 
+          <RasterLayerLibre
             key={`basemap-${index}`}
             id={`base-layer-${index}`}
-            url={[layer.url]}
+            url={expandXyzSubdomains(layer.url)}
             attribution={layer.attribution}
+            tileSize={layer.tileSize}
             visible={index === activeBaseLayer}
           />
         ))}
 
-        {/* Vector Layers from prop - render AFTER base layer so they appear on top */}
-        {allVectorLayers.map((layer) => {
-          const geoJson = layersData[layer.name];
+        {/* Overlay Layers from prop - render AFTER base layer so they appear on top */}
+        {allOverlayLayers.map((layer) => {
           const layerId = `layer-${layer.name.replace(/\s+/g, '-')}`;
+          const isVisible = overlayLayerVisibility[layerId] !== false;
+
+          // Raster overlays (XYZ/WMS) render natively via MapLibre tiles —
+          // they never go through fetchData/dataToGeoJson/layersData.
+          if (layer.source.type === 'xyz' || layer.source.type === 'wms') {
+            const urls = layer.source.type === 'xyz'
+              ? expandXyzSubdomains(layer.source.url)
+              : [buildWmsUrl(layer.source)];
+            return (
+              <RasterLayerLibre
+                key={layerId}
+                id={layerId}
+                url={urls}
+                tileSize={layer.source.tileSize}
+                attribution={layer.source.attribution}
+                visible={isVisible}
+              />
+            );
+          }
+
+          const geoJson = layersData[layer.name];
           const sourceId = `source-${layer.name}`;
-          const isVisible = vectorLayerVisibility[layerId] !== false;
-          
+
           if (!geoJson) return null;
-          
+
           // Apply search filter if present
           const searchQuery = layerSearchQueries[layerId];
           let filteredGeoJson = geoJson;

package/components/Map/MapMdx.tsx

@@ -18,20 +18,26 @@ export function Map(props: MapProps) {
   
   // Memoize array/object props to prevent unnecessary re-renders in MDX
   const stableBaseLayers = useMemo(() => props?.baseLayers, [JSON.stringify(props?.baseLayers || [])]);
-  const stableVectorLayers = useMemo(() => props?.vectorLayers, [JSON.stringify(props?.vectorLayers || [])]);
+  const stableOverlayLayers = useMemo(() => props?.overlayLayers, [JSON.stringify(props?.overlayLayers || [])]);
   const stableGeojson = useMemo(() => props?.geojson, [JSON.stringify(props?.geojson || null)]);
   const stableCsv = useMemo(() => props?.csv, [JSON.stringify(props?.csv || null)]);
   const stableJson = useMemo(() => props?.json, [JSON.stringify(props?.json || null)]);
+  // `directus` feeds the same `implicitSource` → `allOverlayLayers` memo chain
+  // as `geojson`/`csv`/`json`; without stabilising it here an inline
+  // `directus={{ table: '…' }}` object from MDX gets a new identity on every
+  // render and drives the same render loop the others are memoised against.
+  const stableDirectus = useMemo(() => props?.directus, [JSON.stringify(props?.directus || null)]);
 
   return (
-    <MapCore 
-      {...props} 
+    <MapCore
+      {...props}
       center={stableCenter}
       baseLayers={stableBaseLayers}
-      vectorLayers={stableVectorLayers}
+      overlayLayers={stableOverlayLayers}
       geojson={stableGeojson}
       csv={stableCsv}
       json={stableJson}
+      directus={stableDirectus}
     />
   );
 }

package/components/Map/README.md

@@ -0,0 +1,201 @@
+# Map Component
+
+Interactive map built on [MapLibre GL JS](https://maplibre.org/) (via
+`@vis.gl/react-maplibre`). Renders a raster basemap, any number of toggleable
+overlay layers pulled from heterogeneous data sources (GeoJSON, CSV, JSON,
+Directus, a generic API, or raster XYZ/WMS tiles), and a built-in layer
+control for switching basemaps and toggling overlays.
+
+## Basic usage
+
+```mdx
+import { Map } from '@lad-sapienza/scms-core';
+
+<Map />
+```
+
+With no props, `Map` renders a single OSM basemap centered on `0,0` at zoom
+`2`. The shorthand props below cover the common single-layer case without
+touching `overlayLayers` directly:
+
+```mdx
+<Map geojson="/data/sites.geojson" popup="<b>${name}</b>" fitToContent />
+
+<Map csv={{ path: '/data/sites.csv', lng: 'longitude', lat: 'latitude' }} />
+
+<Map directus={{ table: 'sites', geoField: 'location' }} />
+```
+
+`geojson`/`csv`/`json`/`directus` each accept either a bare string (path/URL)
+or an object with `name`, `style`, `popup`, `fitToContent`, `filter` — see
+`MapProps` in [`types.ts`](./types.ts) for the exact shape of each.
+
+## Base layers (`baseLayers`)
+
+Base layers are **radio-exclusive** — exactly one is visible at a time,
+switched via the layer control's "BASE MAPS" section. Accepts either keys
+from the built-in registry ([`defaultBasemaps.ts`](./defaultBasemaps.ts): OSM,
+EsriSatellite, EsriStreets, EsriTopo, GoogleSatellite/Roadmap/Terrain,
+CartoDB, Imperium, CAWM, ...) or custom `BaseLayerConfig` objects, and the two
+forms can be mixed in the same array:
+
+```mdx
+<Map baseLayers={['OSM', 'EsriSatellite']} />
+
+<Map baseLayers={[
+  { name: 'My WMTS', url: 'https://tiles.example.org/{z}/{x}/{y}.png', tileSize: 512 },
+  'OSM',
+]} />
+```
+
+`{s}` in a tile URL (subdomain rotation, e.g. `https://{s}.tile.osm.org/...`)
+is expanded automatically into `a`/`b`/`c`. `tileSize` defaults to 256 and
+only needs setting for services that don't use standard 256px tiles.
+
+## Overlay layers (`overlayLayers`)
+
+Overlays are **independent and toggleable** (checkbox in the layer control) —
+any number can be visible at once, layered on top of the basemap in array
+order. Each entry is a `name` plus a `source`, where `source.type` picks one
+of two families:
+
+**Row/feature sources** — fetched once, converted to GeoJSON, and rendered as
+a MapLibre `circle`/custom-style layer. Supports `style` (paint/layout
+overrides), `popupTemplate`, `fitToContent`, `filter`, `searchInFields`:
+
+| `source.type` | Notes |
+|---|---|
+| `geojson` | `{ data }` inline or `{ url }` to fetch |
+| `csv` | `{ url, lng?, lat?, delimiter?, skipRows? }` — auto-detects lat/lng column names if `lng`/`lat` aren't given |
+| `json` | `{ data }` inline array or `{ url }` |
+| `directus` | Directus collection query, `geoField` names the geometry column |
+| `api` | Generic `{ url, method?, headers?, body?, transformer? }` |
+| `vector` | MapLibre vector-tile source (only produced internally when parsing a full `mapStyle`) |
+
+If two overlay entries point at the exact same `source` (deep-equal), the
+underlying fetch happens only once — each entry's own `filter` is applied on
+top of the shared cached data, so e.g. the same Directus table can back
+several differently-filtered/styled layers without redundant requests.
+
+**Raster tile sources** — rendered directly as MapLibre raster tiles (same
+code path as `baseLayers`), never fetched/converted. `style`, `popupTemplate`,
+`fitToContent`, `filter` and `searchInFields` don't apply to these:
+
+```mdx
+<Map
+  baseLayers={['OSM']}
+  overlayLayers={[{
+    name: 'Satellite',
+    source: { type: 'xyz', url: 'https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}' },
+  }]}
+/>
+```
+
+This is the case that motivated adding raster support to `overlayLayers` in
+the first place: a raster layer (historical map, satellite imagery, ...)
+shown as an independent overlay on top of a basemap the user picks — not
+possible before, since a raster source could previously only be a
+radio-exclusive `baseLayers` entry.
+
+`XyzSourceConfig`: `{ type: 'xyz', url, tileSize?, attribution? }` — same
+`{s}` subdomain expansion and `tileSize` default as `baseLayers`.
+
+`WmsSourceConfig`: `{ type: 'wms', url, layers, format?, version?, transparent?, styles?, crs?, tileSize?, attribution? }` builds a GetMap tile URL
+using MapLibre's `{bbox-epsg-3857}` placeholder. Defaults: `format:
+'image/png'`, `version: '1.3.0'`, `transparent: true`, `crs: 'EPSG:3857'`,
+`tileSize: 256`.
+
+```mdx
+<Map overlayLayers={[{
+  name: 'Historical layer',
+  source: {
+    type: 'wms',
+    url: 'https://wms.example.org/geoserver/wms',
+    layers: 'workspace:layer_name',
+  },
+}]} />
+```
+
+Both raster source types need the tile server to send CORS headers
+(`Access-Control-Allow-Origin`) — MapLibre renders tiles as WebGL textures,
+which browsers refuse to upload cross-origin without a successful CORS
+check, unlike a plain `<img>`-based renderer (e.g. Leaflet). If tiles fail to
+load with a CORS error in the console, the fix is on the tile server, not
+here — for object-storage-backed static tile sets (e.g. OpenStack Swift),
+this is typically one container-metadata header
+(`X-Container-Meta-Access-Control-Allow-Origin: *`).
+
+## Controls
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `layerControl` | `boolean \| ControlPosition` | `'top-right'` | Basemap radio + overlay checkboxes. `false` hides it. |
+| `navigationControl` | `ControlPosition` | `'top-left'` | Zoom +/- and compass |
+| `geolocateControl` | `ControlPosition` | — | "find my location" |
+| `fullscreenControl` | `ControlPosition` | — | Fullscreen toggle |
+| `scaleControl` | `ControlPosition` | — | Scale bar |
+
+`ControlPosition` is one of `'top-right' | 'top-left' | 'bottom-right' |
+'bottom-left'`.
+
+## Full style mode (`mapStyle`)
+
+Pass a full MapLibre style URL/object via `mapStyle` to bypass `baseLayers`/
+`overlayLayers` resolution entirely — raster sources in the style become
+basemap entries, vector-tile layers become overlay entries, and
+`styleOverrides` can patch individual style layers' `paint`/`layout` plus
+add `popupTemplate`/`fitToContent`/`visible` (properties the style spec
+itself has no room for). See `MapProps` in [`types.ts`](./types.ts) for the
+exact shape.
+
+## Props
+
+### `Map`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `height` | `string` | `'600px'` | CSS height |
+| `center` | `string` | `'0,0,2'` | `"lng,lat,zoom"` |
+| `baseLayers` | `(BaseLayerConfig \| BasemapKey)[]` | `['OSM']` | See above |
+| `overlayLayers` | `OverlayLayerConfig[]` | `[]` | See above |
+| `mapStyle` | `string \| object` | — | Full MapLibre style, see above |
+| `styleOverrides` | `object` | — | Per-layer patches when using `mapStyle` |
+| `geojson` / `csv` / `json` / `directus` | — | — | Single-layer shorthands, see Basic usage |
+| `sprite` | `string` | — | Sprite URL |
+
+### `BaseLayerConfig`
+
+| Field | Type | Description |
+|---|---|---|
+| `name` | `string` | Label in the layer control |
+| `url` | `string` | Tile URL template, `{z}/{x}/{y}` (+ optional `{s}`) |
+| `attribution` | `string?` | Attribution HTML |
+| `tileSize` | `number?` | Default 256 |
+
+### `OverlayLayerConfig`
+
+| Field | Type | Description |
+|---|---|---|
+| `name` | `string` | Label in the layer control |
+| `source` | `SourceConfig \| XyzSourceConfig \| WmsSourceConfig` | See above |
+| `style` | `any?` | MapLibre paint/layout override (row/feature sources only) |
+| `popupTemplate` | `string?` | e.g. `"<b>${Title}</b>: ${Description}"` (row/feature sources only) |
+| `visible` | `boolean?` | Initial visibility (default `true`) |
+| `fitToContent` | `boolean?` | Fit map bounds to this layer's data on load (row/feature sources only) |
+| `filter` | `FilterObject \| ((feature) => boolean)?` | Client-side filter (row/feature sources only) |
+| `searchInFields` | `SearchInFields?` | Enables the per-layer search UI (row/feature sources only) |
+
+## Architecture notes
+
+- `Map.tsx` renders `RasterLayerLibre` for every `baseLayers` entry and for
+  any `overlayLayers` entry whose `source.type` is `xyz`/`wms`; everything
+  else goes through `fetchData`/`dataToGeoJson`
+  ([`utils/data-fetcher.ts`](../../utils/data-fetcher.ts),
+  [`utils.ts`](./utils.ts)) into a MapLibre `geojson` source.
+- `LayerControl.tsx` is a plain MapLibre `IControl` (not a React child of the
+  map) so it survives the basemap/overlay state living in `Map.tsx`'s own
+  React state rather than needing a portal.
+- `expandXyzSubdomains`/`buildWmsUrl` (in [`utils.ts`](./utils.ts)) are the
+  only two functions that build tile URL templates — both `baseLayers` and
+  raster `overlayLayers` go through them, so there's one place to fix or
+  extend tile-URL construction.

package/components/Map/index.ts

@@ -2,5 +2,5 @@ export { Map } from './MapMdx';
 export { Map as MapCore } from './Map';
 export { defaultBasemaps, getBasemap, getBasemaps } from './defaultBasemaps';
 export type { BasemapKey } from './defaultBasemaps';
-export type { VectorLayerConfig } from './types';
+export type { OverlayLayerConfig } from './types';
 export * from './types';

package/components/Map/types.ts

@@ -71,30 +71,62 @@ export interface BaseLayerConfig {
   name: string;
   url: string;
   attribution?: string;
+  /** Tile size in pixels, for services that don't use 256px tiles (default: 256) */
+  tileSize?: number;
 }
 
-export interface VectorLayerConfig {
+/**
+ * XYZ raster tile source — for a raster layer used as an independent,
+ * toggleable overlay rather than a radio-exclusive basemap.
+ */
+export interface XyzSourceConfig {
+  type: 'xyz';
+  /** Tile URL template with {z}/{x}/{y}, optionally {s} (expanded to a/b/c) */
+  url: string;
+  tileSize?: number;
+  attribution?: string;
+}
+
+/**
+ * WMS raster source — builds a GetMap tile URL template from friendly params.
+ */
+export interface WmsSourceConfig {
+  type: 'wms';
+  /** WMS endpoint base URL */
+  url: string;
+  /** GetMap LAYERS param */
+  layers: string;
+  format?: string;
+  version?: string;
+  transparent?: boolean;
+  styles?: string;
+  crs?: string;
+  tileSize?: number;
+  attribution?: string;
+}
+
+export interface OverlayLayerConfig {
   /** Layer name/ID */
   name: string;
-  
+
   /** Data source configuration */
-  source: SourceConfig;
-  
+  source: SourceConfig | XyzSourceConfig | WmsSourceConfig;
+
   /** Layer style (MapLibre paint/layout properties) */
   style?: any;
-  
+
   /** Popup template string (e.g., "<b>${Title}</b>: ${Description}") */
   popupTemplate?: string;
-  
+
   /** Initial visibility */
   visible?: boolean;
-  
+
   /** Fit map bounds to layer content */
   fitToContent?: boolean;
 
   /** Optional client-side filter for features */
   filter?: FilterObject | ((feature: any) => boolean);
-  
+
   /** Search configuration - defines which fields are searchable */
   searchInFields?: SearchInFields;
 }
@@ -128,8 +160,8 @@ export interface MapProps {
   /** Base layers configuration (can be array of configs or array of basemap keys) */
   baseLayers?: BaseLayerConfig[] | BasemapKey[];
   
-  /** Vector layers configuration (alternative to children for hydration-safe usage) */
-  vectorLayers?: VectorLayerConfig[];
+  /** Overlay layers configuration (alternative to children for hydration-safe usage) */
+  overlayLayers?: OverlayLayerConfig[];
   
   /** Controls positions (null/undefined to hide) */
   geolocateControl?: ControlPosition;

package/components/Map/utils.ts

@@ -4,6 +4,7 @@
 
 import type { DataRow } from '../../utils/data-fetcher';
 import type { FeatureCollection, Feature, Geometry } from 'geojson';
+import type { WmsSourceConfig } from './types';
 
 /**
  * Tries to identify latitude and longitude fields from a data row
@@ -116,6 +117,49 @@ export function dataToGeoJson(
   };
 }
 
+/**
+ * Expands an XYZ tile URL template's {s} subdomain placeholder into the
+ * standard a/b/c rotation (as Leaflet does natively). Returns the url
+ * unchanged, wrapped in an array, if it has no {s} placeholder.
+ */
+export function expandXyzSubdomains(url: string): string[] {
+  if (!url.includes('{s}')) return [url];
+  return ['a', 'b', 'c'].map(s => url.replace('{s}', s));
+}
+
+/**
+ * Builds a WMS GetMap tile URL template from friendly params, using
+ * MapLibre's {bbox-epsg-3857} placeholder for the per-tile bounding box.
+ */
+export function buildWmsUrl(source: WmsSourceConfig): string {
+  const {
+    url,
+    layers,
+    format = 'image/png',
+    version = '1.3.0',
+    transparent = true,
+    styles = '',
+    crs = 'EPSG:3857',
+    tileSize = 256
+  } = source;
+
+  const params = new URLSearchParams({
+    service: 'WMS',
+    request: 'GetMap',
+    version,
+    layers,
+    styles,
+    format,
+    transparent: String(transparent),
+    width: String(tileSize),
+    height: String(tileSize),
+    crs
+  });
+
+  const separator = url.includes('?') ? '&' : '?';
+  return `${url}${separator}${params.toString()}&bbox={bbox-epsg-3857}`;
+}
+
 /**
  * Escapes a string for safe interpolation into HTML markup/attributes.
  */

package/components/ZoteroGeoViewer/ZoteroGeoViewer.tsx

@@ -360,7 +360,7 @@ export function ZoteroGeoViewer(props: ZoteroGeoViewerProps) {
             height={mapHeight}
             center={mapCenter}
             baseLayers={['EsriSatellite', 'GoogleTerrain', 'Imperium']}
-            vectorLayers={mapCenter && geojson && geojson.features.length > 0 ? [{
+            overlayLayers={mapCenter && geojson && geojson.features.length > 0 ? [{
               name: t('zoteroGeoViewer.layerName'),
               source: { type: 'geojson', data: geojson },
               style: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lad-sapienza/scms-core",
-  "version": "0.1.0-alpha.7",
+  "version": "0.1.0-alpha.9",
   "description": "Framework components and Astro integrations for s:CMS — DataTb, Gallery, Map, ZoteroGeoViewer, Record.",
   "type": "module",
   "license": "BSD-0-Clause",