@teamimpact/veda-ui-blocks 0.1.0-beta.11 → 0.1.0-beta.12

package/dist/index.d.ts

@@ -318,9 +318,6 @@ type TagProps = {
  */
 declare function Tag({ variant, size, color, bgColor, borderColor, textColor, icon, onClose, children, className, }: TagProps): react_jsx_runtime.JSX.Element;
 
-/** NASA Blue Marble imagery basemap */
-declare const NASA_BLUE_MARBLE_BASEMAP_STYLE: StyleSpecification;
-
 interface GeoConfigProviderProps {
     stacApiUrl?: string;
     titilerBaseUrl?: string;
@@ -337,20 +334,22 @@ type TileMatrixSet = "WebMercatorQuad" | "GDALWebMercatorQuad" | "WorldCRS84Quad
 type StacRasterLayerConfig = {
     type: "raster";
     collectionId: string;
+    collectionAssetId: string;
     dateRange: DateRange;
     tileMatrixSet?: TileMatrixSet;
+    hideLegend?: boolean;
 };
 interface GradientLegendProps {
     type: "gradient";
-    colorStops: string[];
+    colorStops?: string[];
     title?: string;
     description?: string;
     provider?: string;
     spatialExtent?: string;
     timeDensity?: string;
     unit?: string;
-    min: number;
-    max: number;
+    min?: number;
+    max?: number;
 }
 type LegendProps = GradientLegendProps & {
     initialExpanded?: boolean;
@@ -358,9 +357,32 @@ type LegendProps = GradientLegendProps & {
 
 declare function Legend({ initialExpanded, ...props }: LegendProps): react_jsx_runtime.JSX.Element;
 
+/** NASA Blue Marble imagery basemap */
+declare const NASA_BLUE_MARBLE_BASEMAP_STYLE: StyleSpecification;
+/** Carto Dark Matter raster basemap without labels */
+declare const CARTO_DARK_BASEMAP_STYLE: StyleSpecification;
+/**
+ * Carto Dark Matter vector style with labels.
+ * Data layers should render beneath `waterway_label`.
+ */
+declare const CARTO_DARK_WITH_LABELS_BASEMAP_STYLE = "https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json";
+declare const CARTO_LABELS_LAYER_ID = "waterway_label";
+/**
+ * OpenFreeMap Dark vector style.
+ * Data layers should render beneath `highway_name_other`.
+ */
+declare const OPEN_FREE_MAP_DARK_BASEMAP_STYLE = "https://tiles.openfreemap.org/styles/dark";
+declare const OPEN_FREE_MAP_LABELS_LAYER_ID = "highway_name_other";
+/**
+ * Maps vector basemap styles to the first label layer that should render
+ * above data overlays.
+ */
+declare const BASEMAP_LABEL_LAYER_IDS: Record<string, string>;
+type BaseMaps = keyof typeof BASEMAP_LABEL_LAYER_IDS;
+
 type StacCompareMapProps = {
-    /** MapLibre base map style URL or style object. */
-    baseMapStyle?: string | StyleSpecification;
+    /** MapLibre base map style URL or style object. Defaults to Carto Dark with labels. For known vector styles the label layer is derived automatically so STAC data renders beneath labels. */
+    baseMapStyle?: BaseMaps | StyleSpecification;
     /** Initial map center (longitude/latitude), zoom level, and optional bearing/pitch. MapLibre applies defaults for any properties not provided. */
     initialViewState?: Partial<ViewState>;
     /** Layer config for the left panel. */
@@ -394,8 +416,8 @@ type StacCompareMapProps = {
 declare function StacCompareMap({ baseMapStyle, initialViewState, leftLayerConfig, rightLayerConfig, className, }: StacCompareMapProps): react_jsx_runtime.JSX.Element;
 
 type StacSingleLayerMapProps = {
-    /** MapLibre base map style URL or style object. Defaults to NASA Blue Marble imagery. */
-    baseMapStyle?: string | StyleSpecification;
+    /** MapLibre base map style URL or style object. Defaults to Carto Dark with labels. For known vector styles the label layer is derived automatically so STAC data renders beneath labels. */
+    baseMapStyle?: BaseMaps | StyleSpecification;
     /** Initial map center (longitude/latitude), zoom level, and optional bearing/pitch. MapLibre applies defaults for any properties not provided. */
     initialViewState?: Partial<ViewState>;
     /** STAC collection and date range to fetch and display as a raster tile layer. */
@@ -420,4 +442,4 @@ type StacSingleLayerMapProps = {
  */
 declare function StacSingleLayerMap({ baseMapStyle, initialViewState, layerConfig, }: StacSingleLayerMapProps): react_jsx_runtime.JSX.Element;
 
-export { Banner, type BannerProps, Card, CardCTA, type CardCTAProps, CardDetailed, type CardDetailedProps, CardMini, type CardMiniProps, type CardProps, CardSimple, type CardSimpleProps, Footer, type FooterProps, GeoConfigProvider, type GeoConfigProviderProps, Header, type HeaderProps, Legend, type LegendProps, Link, type LinkProps, NASA_BLUE_MARBLE_BASEMAP_STYLE, StacCompareMap, type StacCompareMapProps, StacSingleLayerMap, type StacSingleLayerMapProps, Tag, type TagProps };
+export { Banner, type BannerProps, CARTO_DARK_BASEMAP_STYLE, CARTO_DARK_WITH_LABELS_BASEMAP_STYLE, CARTO_LABELS_LAYER_ID, Card, CardCTA, type CardCTAProps, CardDetailed, type CardDetailedProps, CardMini, type CardMiniProps, type CardProps, CardSimple, type CardSimpleProps, Footer, type FooterProps, GeoConfigProvider, type GeoConfigProviderProps, Header, type HeaderProps, Legend, type LegendProps, Link, type LinkProps, NASA_BLUE_MARBLE_BASEMAP_STYLE, OPEN_FREE_MAP_DARK_BASEMAP_STYLE, OPEN_FREE_MAP_LABELS_LAYER_ID, StacCompareMap, type StacCompareMapProps, StacSingleLayerMap, type StacSingleLayerMapProps, Tag, type TagProps };

package/dist/index.js

@@ -26,6 +26,7 @@ var isArray = (as) => Array.isArray(as);
 var isEmptyArray = (as) => isArray(as) && as.length === 0;
 var isNonEmptyArray = (as) => isArray(as) && as.length > 0;
 var getTypedValues = Object.values;
+var getTypedEntries = Object.entries;
 
 // src/utils/component-utils.tsx
 var get_external_anchor_props = (isExternal) => isExternal ? { target: "_blank", rel: "noopener noreferrer" } : {};
@@ -737,43 +738,17 @@ function Tag({
   ] });
 }
 
+// src/geo/GeoConfigProvider.tsx
+import { StacApiProvider } from "@developmentseed/stac-react";
+import { createContext, useContext } from "react";
+
 // src/geo/constants.ts
-var NASA_BLUE_MARBLE_BASEMAP_STYLE = {
-  version: 8,
-  sources: {
-    "nasa-blue-marble": {
-      type: "raster",
-      tiles: [
-        "https://gibs.earthdata.nasa.gov/wmts/epsg3857/best/BlueMarble_NextGeneration/default/GoogleMapsCompatible_Level8/{z}/{y}/{x}.jpeg"
-      ],
-      tileSize: 256,
-      maxzoom: 8,
-      attribution: "Imagery courtesy NASA EOSDIS/GIBS"
-    }
-  },
-  layers: [
-    {
-      id: "nasa-blue-marble",
-      type: "raster",
-      source: "nasa-blue-marble"
-    }
-  ]
-};
 var STAC_API_URL = "https://openveda.cloud/api/stac";
 var TITILER_BASE_URL = "https://openveda.cloud/api/raster";
-var DEFAULT_RENDER_PARAMS = {
-  assets: ["cog_default"],
-  rescale: "0,0.0001",
-  resampling: "bilinear",
-  colormap_name: "viridis",
-  bidx: [1]
-};
 var DEFAULT_TILE_MATRIX_SET = "WebMercatorQuad";
 var STAC_COLORSTOP_RGBA_ARG_COUNT = 4;
 
 // src/geo/GeoConfigProvider.tsx
-import { StacApiProvider } from "@developmentseed/stac-react";
-import { createContext, useContext } from "react";
 import { jsx as jsx14 } from "react/jsx-runtime";
 var GeoConfigContext = createContext(null);
 function useGeoConfig() {
@@ -792,7 +767,7 @@ function GeoConfigProvider({
 // src/geo/Legend/Legend.tsx
 import { Icon as Icon3 } from "@trussworks/react-uswds";
 import { useState as useState3 } from "react";
-import { jsx as jsx15, jsxs as jsxs13 } from "react/jsx-runtime";
+import { Fragment as Fragment3, jsx as jsx15, jsxs as jsxs13 } from "react/jsx-runtime";
 function Legend({ initialExpanded = false, ...props }) {
   const { title, description, unit, min, max, colorStops, provider, spatialExtent, timeDensity } = props;
   const [isExpanded, setIsExpanded] = useState3(initialExpanded);
@@ -815,19 +790,21 @@ function Legend({ initialExpanded = false, ...props }) {
         }
       )
     ] }),
-    /* @__PURE__ */ jsx15("div", { className: "blocks-legend__gradient-bar", children: /* @__PURE__ */ jsx15(
-      "div",
-      {
-        className: "blocks-legend__gradient",
-        style: {
-          background: `linear-gradient(to right, ${colorStops.join(", ")})`
+    colorStops && /* @__PURE__ */ jsxs13(Fragment3, { children: [
+      /* @__PURE__ */ jsx15("div", { className: "blocks-legend__gradient-bar", children: /* @__PURE__ */ jsx15(
+        "div",
+        {
+          className: "blocks-legend__gradient",
+          style: {
+            background: `linear-gradient(to right, ${colorStops.join(", ")})`
+          }
         }
-      }
-    ) }),
-    /* @__PURE__ */ jsxs13("div", { className: "blocks-legend__labels", children: [
-      /* @__PURE__ */ jsx15("span", { className: "blocks-legend__min", children: min }),
-      /* @__PURE__ */ jsx15("span", { className: "blocks-legend__unit", children: unit }),
-      /* @__PURE__ */ jsx15("span", { className: "blocks-legend__max", children: max })
+      ) }),
+      isDefined(min) && isDefined(max) && /* @__PURE__ */ jsxs13("div", { className: "blocks-legend__labels", children: [
+        /* @__PURE__ */ jsx15("span", { className: "blocks-legend__min", children: min }),
+        /* @__PURE__ */ jsx15("span", { className: "blocks-legend__unit", children: unit }),
+        /* @__PURE__ */ jsx15("span", { className: "blocks-legend__max", children: max })
+      ] })
     ] }),
     isExpanded && description && /* @__PURE__ */ jsx15("div", { className: "blocks-legend__description", children: /* @__PURE__ */ jsx15("div", { className: "blocks-legend__description-inner", children: description }) })
   ] });
@@ -850,7 +827,17 @@ function AttributionMapControl({ position = "top-right" }) {
   return null;
 }
 
-// src/geo/utils/formatDateRange.ts
+// src/geo/utils/stac.formatters.ts
+var formatSpatialExtent = (spatialExtent) => {
+  const [minX, minY, maxX, maxY] = spatialExtent?.bbox?.[0] ?? [];
+  if (minX === void 0 || minY === void 0 || maxX === void 0 || maxY === void 0)
+    return void 0;
+  return maxX - minX >= 359 && maxY - minY >= 179 ? "global" : "regional";
+};
+function formatDateToISODatetime(date, isEndOfDay) {
+  const datetime = /* @__PURE__ */ new Date(`${date}${isEndOfDay ? "T23:59:59Z" : "T00:00:00Z"}`);
+  return datetime.toISOString();
+}
 function formatDateRange(dateRange) {
   const from = /* @__PURE__ */ new Date(`${dateRange.from}T00:00:00Z`);
   const to = /* @__PURE__ */ new Date(`${dateRange.to}T00:00:00Z`);
@@ -875,6 +862,18 @@ function formatDateRange(dateRange) {
   });
   return `${fromStr} \u2013 ${toStr}`;
 }
+var formatRenderPropertiesToQuery = (renderProperties) => {
+  const query = new URLSearchParams();
+  getTypedEntries(renderProperties).forEach(([key, value]) => {
+    if (!isDefined(value)) return;
+    if (isArray(value)) {
+      value.map((v) => query.append(key, String(v)));
+    } else {
+      query.append(key, String(value));
+    }
+  });
+  return query.toString();
+};
 
 // src/geo/DateChip/DateChip.tsx
 import { jsx as jsx16 } from "react/jsx-runtime";
@@ -886,43 +885,11 @@ function DateChip({ left, right }) {
 // src/geo/hooks/useStacRasterLayer.ts
 import { useCollection } from "@developmentseed/stac-react";
 
-// src/geo/hooks/useMosaicTiles.ts
+// src/geo/hooks/useRasterTiles.ts
 import { useQuery } from "@tanstack/react-query";
 
-// src/geo/api/titiler/fetchTilejson.ts
-async function fetchTilejson(tilejsonUrl, queryString) {
-  const response = await fetch(`${tilejsonUrl}?${queryString}`);
-  if (!response.ok) {
-    const error = { detail: `Failed to fetch tilejson: ${response.statusText}` };
-    throw error;
-  }
-  const tilejson = await response.json();
-  if (!tilejson.tiles?.[0]) {
-    const error = { detail: "No tile URL found in response" };
-    throw error;
-  }
-  return tilejson.tiles[0];
-}
-
-// src/geo/api/titiler/mosaicLinks.ts
-function findTileLink(links) {
-  return links.find((link) => link.rel === "tiles") ?? links.at(1) ?? links.at(0) ?? null;
-}
-function buildTilejsonUrl(tileLinkHref, tileMatrixSet) {
-  return tileLinkHref.replace("/{tileMatrixSetId}", `/${tileMatrixSet}`);
-}
-function extractTileUrl(registrationResponse, tileMatrixSet) {
-  const tileLink = findTileLink(registrationResponse.links);
-  if (!tileLink?.href) {
-    const error = { detail: "No tile URL found in registration response" };
-    throw error;
-  }
-  const tilejsonUrl = buildTilejsonUrl(tileLink.href, tileMatrixSet);
-  return tilejsonUrl;
-}
-
-// src/geo/api/titiler/registerMosaic.ts
-async function registerMosaic(request) {
+// src/geo/api/titiler/rasterSearchRegister.ts
+async function rasterSearchRegister(request) {
   const { rasterApiUrl, collectionId, datetime } = request;
   const response = await fetch(`${rasterApiUrl}/searches/register`, {
     method: "POST",
@@ -939,93 +906,70 @@ async function registerMosaic(request) {
     };
     throw error;
   }
-  return response.json();
+  const responseJson = await response.json();
+  return responseJson;
 }
 
-// src/geo/api/titiler/fetchMosaicTileUrl.ts
-var TILE_PARAMS = {
-  ASSETS: "assets",
-  RESCALE: "rescale",
-  RESAMPLING: "resampling",
-  COLORMAP_NAME: "colormap_name",
-  BIDX: "bidx"
-};
-function buildQueryParams(sourceParams) {
-  const params = new URLSearchParams();
-  if (sourceParams.assets) params.append(TILE_PARAMS.ASSETS, sourceParams.assets.join(","));
-  if (sourceParams.rescale) params.append(TILE_PARAMS.RESCALE, sourceParams.rescale);
-  if (sourceParams.resampling) params.append(TILE_PARAMS.RESAMPLING, sourceParams.resampling);
-  if (sourceParams.colormap_name)
-    params.append(TILE_PARAMS.COLORMAP_NAME, sourceParams.colormap_name);
-  if (sourceParams.bidx) params.append(TILE_PARAMS.BIDX, sourceParams.bidx.join(","));
-  return params;
-}
-async function fetchMosaicTileUrl(request) {
-  const { sourceParams, tileMatrixSet } = request;
-  const queryParams = buildQueryParams(sourceParams);
-  const queryString = queryParams.toString();
-  const registrationResponse = await registerMosaic(request);
-  const tilejsonUrl = extractTileUrl(registrationResponse, tileMatrixSet);
-  return fetchTilejson(tilejsonUrl, queryString);
+// src/geo/api/titiler/rasterSearchTileJson.ts
+async function rasterSearchTileJson({
+  rasterApiUrl,
+  searchId,
+  renderProperties,
+  tileMatrixSet
+}) {
+  const tilejsonUrl = `${rasterApiUrl}/searches/${searchId}/${tileMatrixSet}/tilejson.json`;
+  const queryString = formatRenderPropertiesToQuery(renderProperties);
+  const response = await fetch(`${tilejsonUrl}?${queryString}`);
+  if (!response.ok) {
+    const error = { detail: `Failed to fetch tilejson: ${response.statusText}` };
+    throw error;
+  }
+  const responseJson = await response.json();
+  return responseJson;
 }
 
-// src/geo/utils/resolveAssetName.ts
-function resolveAssetName(collection) {
-  if (collection.renders?.dashboard?.assets?.[0]) {
-    return collection.renders.dashboard.assets[0];
-  }
-  if (collection.item_assets?.cog_default) {
-    return "cog_default";
-  }
-  if (collection.item_assets) {
-    const firstKey = Object.keys(collection.item_assets)[0];
-    if (firstKey) return firstKey;
-  }
-  return "cog_default";
+// src/geo/api/titiler/fetchRasterTileUrl.ts
+async function fetchRasterTileUrl(request) {
+  const { collectionId, datetime, rasterApiUrl, renderProperties, tileMatrixSet } = request;
+  const { id: searchId } = await rasterSearchRegister({ collectionId, datetime, rasterApiUrl });
+  const { tiles } = await rasterSearchTileJson({
+    rasterApiUrl,
+    searchId,
+    renderProperties,
+    tileMatrixSet
+  });
+  return tiles[0];
 }
 
-// src/geo/hooks/useMosaicTiles.ts
-function useMosaicTiles(rasterLayerConfig, collection) {
+// src/geo/hooks/useRasterTiles.ts
+function useRasterTiles(rasterLayerConfig, collection) {
   const { titilerBaseUrl } = useGeoConfig();
-  const { collectionId, dateRange, tileMatrixSet = DEFAULT_TILE_MATRIX_SET } = rasterLayerConfig;
-  const datetime = dateRange.from === dateRange.to ? dateRange.from : `${dateRange.from}/${dateRange.to}`;
-  const assetName = collection ? resolveAssetName(collection) : DEFAULT_RENDER_PARAMS.assets[0];
-  const colormapName = collection?.renders?.dashboard?.colormap_name ?? DEFAULT_RENDER_PARAMS.colormap_name;
-  const rescale = collection?.renders?.dashboard?.rescale?.join(",") ?? DEFAULT_RENDER_PARAMS.rescale;
-  const resampling = collection?.renders?.dashboard?.resampling ?? DEFAULT_RENDER_PARAMS.resampling;
-  const request = {
-    rasterApiUrl: titilerBaseUrl,
+  const {
     collectionId,
-    datetime,
-    sourceParams: {
-      ...DEFAULT_RENDER_PARAMS,
-      assets: [assetName],
-      colormap_name: colormapName,
-      rescale,
-      resampling
-    },
-    tileMatrixSet
-  };
+    collectionAssetId,
+    dateRange,
+    tileMatrixSet = DEFAULT_TILE_MATRIX_SET
+  } = rasterLayerConfig;
+  const datetime = `${formatDateToISODatetime(dateRange.from)}/${formatDateToISODatetime(dateRange.to, true)}`;
+  const renderProperties = collection?.renders?.[collectionAssetId] ?? {};
   return useQuery({
-    queryKey: [collectionId, dateRange, titilerBaseUrl, assetName],
-    queryFn: () => fetchMosaicTileUrl(request),
+    queryKey: [collectionId, collectionAssetId, datetime, titilerBaseUrl],
+    queryFn: () => fetchRasterTileUrl({
+      rasterApiUrl: titilerBaseUrl,
+      collectionId,
+      datetime,
+      renderProperties,
+      tileMatrixSet
+    }),
     staleTime: 30 * 60 * 1e3,
     gcTime: 60 * 60 * 1e3,
-    enabled: !!collectionId && !!dateRange?.from && !!dateRange?.to
+    enabled: isDefined(collection) && !isEmptyObject(collection) && !isEmptyObject(renderProperties)
   });
 }
 
 // src/geo/hooks/useStacRasterLegend.ts
 import { useQuery as useQuery2 } from "@tanstack/react-query";
 
-// src/geo/utils/stac.formatters.ts
-var formatSpatialExtent = (spatialExtent) => {
-  const [minX, minY, maxX, maxY] = spatialExtent?.bbox?.[0] ?? [];
-  if (minX === void 0 || minY === void 0 || maxX === void 0 || maxY === void 0)
-    return void 0;
-  return maxX - minX >= 359 && maxY - minY >= 179 ? "global" : "regional";
-};
-
 // src/geo/utils/stac.typeguards.ts
 var isRgbaColorStopMap = (value) => {
   return !isNil(value) && isObject(value) && !isEmptyObject(value) && getTypedValues(value).every(
@@ -1034,53 +978,58 @@ var isRgbaColorStopMap = (value) => {
 };
 
 // src/geo/utils/extractLegendProps.ts
-function extractLegendProps(collection, colorStopMap) {
-  const rescale = collection.renders?.dashboard?.rescale?.[0];
-  if (!rescale) return null;
-  if (!isRgbaColorStopMap(colorStopMap)) return null;
-  const colorStops = getTypedValues(colorStopMap).map((rgba) => `rgba(${rgba.join(",")})`);
+function extractLegendProps(collection, collectionAssetId, colorStopMap) {
+  const rescale = collection.renders?.[collectionAssetId]?.rescale?.[0];
+  let colorStops;
+  if (isRgbaColorStopMap(colorStopMap)) {
+    colorStops = getTypedValues(colorStopMap).map((rgba) => `rgba(${rgba.join(",")})`);
+  }
   const title = collection.title;
   const description = collection.description;
   const provider = collection.providers?.[0]?.name;
   const timeDensity = collection.properties?.["dashboard:time_density"];
   const spatialExtent = formatSpatialExtent(collection.extent?.spatial);
-  const assetName = resolveAssetName(collection);
-  const unit = collection.item_assets?.[assetName]?.["raster:bands"]?.[0]?.unit;
+  const unit = collection.item_assets?.[collectionAssetId]?.["raster:bands"]?.[0]?.unit;
   return {
     type: "gradient",
-    ...title && { title },
-    ...description && { description },
-    min: rescale[0],
-    max: rescale[1],
-    colorStops,
-    ...provider && { provider },
-    ...timeDensity && { timeDensity },
-    ...spatialExtent && { spatialExtent },
-    ...unit && { unit }
+    ...{ title },
+    ...{ description },
+    // TODO 271: existing datasets for use do not include rescale, are we certain this is required
+    // is there another way to determine min and max
+    ...isDefined(rescale) ? { min: rescale[0] } : {},
+    ...isDefined(rescale) ? { max: rescale[1] } : {},
+    ...{ colorStops },
+    ...{ provider },
+    ...{ timeDensity },
+    ...{ spatialExtent },
+    ...{ unit }
   };
 }
 
 // src/geo/hooks/useStacRasterLegend.ts
-function useStacRasterLegend(collection) {
+function useStacRasterLegend(collectionAssetId, collection, options) {
   const { titilerBaseUrl } = useGeoConfig();
+  const { hideLegend } = options ?? {};
   const query = useQuery2({
-    queryKey: ["legend", collection, titilerBaseUrl],
+    queryKey: ["legend", collection, collectionAssetId, titilerBaseUrl],
     queryFn: async () => {
       if (!collection) return null;
-      const colormapName = collection?.renders?.dashboard?.colormap_name;
-      if (!colormapName) return null;
-      const response = await fetch(`${titilerBaseUrl}/colorMaps/${colormapName}`);
-      if (!response.ok) {
-        const error = {
-          detail: `Colormap "${colormapName}" not found (HTTP ${response.status})`,
-          status: response.status
-        };
-        throw error;
+      let colormap;
+      const colormapName = collection?.renders?.[collectionAssetId]?.colormap_name;
+      if (colormapName) {
+        const response = await fetch(`${titilerBaseUrl}/colorMaps/${colormapName}`);
+        if (!response.ok) {
+          const error = {
+            detail: `Colormap "${colormapName}" not found (HTTP ${response.status})`,
+            status: response.status
+          };
+          throw error;
+        }
+        colormap = await response.json();
       }
-      const colorMap = await response.json();
-      return extractLegendProps(collection, colorMap);
+      return extractLegendProps(collection, collectionAssetId, colormap);
     },
-    enabled: !!collection
+    enabled: !!collection && !hideLegend
   });
   return {
     legend: query.data ?? null,
@@ -1091,7 +1040,7 @@ function useStacRasterLegend(collection) {
 
 // src/geo/hooks/useStacRasterLayer.ts
 function useStacRasterLayer(rasterLayerConfig) {
-  const { collectionId } = rasterLayerConfig;
+  const { collectionId, collectionAssetId, hideLegend } = rasterLayerConfig;
   const {
     collection,
     isLoading: isLoadingCollection,
@@ -1102,12 +1051,12 @@ function useStacRasterLayer(rasterLayerConfig) {
     data: tiles,
     isLoading: tilesetLoading,
     error: tilesetError
-  } = useMosaicTiles(rasterLayerConfig, extCollection);
+  } = useRasterTiles(rasterLayerConfig, extCollection);
   const {
     legend,
     isLoading: isLoadingLegend,
     error: legendError
-  } = useStacRasterLegend(extCollection);
+  } = useStacRasterLegend(collectionAssetId, extCollection, { hideLegend });
   return {
     mapSource: {
       tiles: tiles ?? null
@@ -1118,6 +1067,53 @@ function useStacRasterLayer(rasterLayerConfig) {
   };
 }
 
+// src/geo/stac.basemaps.ts
+var createRasterBasemapStyle = ({
+  id,
+  tiles,
+  maxzoom,
+  attribution
+}) => ({
+  version: 8,
+  sources: {
+    [id]: {
+      type: "raster",
+      tiles,
+      tileSize: 256,
+      maxzoom,
+      attribution
+    }
+  },
+  layers: [{ id, type: "raster", source: id }]
+});
+var NASA_BLUE_MARBLE_BASEMAP_STYLE = createRasterBasemapStyle({
+  id: "nasa-blue-marble",
+  tiles: [
+    "https://gibs.earthdata.nasa.gov/wmts/epsg3857/best/BlueMarble_NextGeneration/default/GoogleMapsCompatible_Level8/{z}/{y}/{x}.jpeg"
+  ],
+  maxzoom: 8,
+  attribution: "Imagery courtesy NASA EOSDIS/GIBS"
+});
+var CARTO_DARK_BASEMAP_STYLE = createRasterBasemapStyle({
+  id: "carto-dark",
+  tiles: [
+    "https://a.basemaps.cartocdn.com/dark_nolabels/{z}/{x}/{y}.png",
+    "https://b.basemaps.cartocdn.com/dark_nolabels/{z}/{x}/{y}.png",
+    "https://c.basemaps.cartocdn.com/dark_nolabels/{z}/{x}/{y}.png",
+    "https://d.basemaps.cartocdn.com/dark_nolabels/{z}/{x}/{y}.png"
+  ],
+  maxzoom: 19,
+  attribution: "Map tiles by Carto, under CC BY 3.0. Data by OpenStreetMap, under ODbL."
+});
+var CARTO_DARK_WITH_LABELS_BASEMAP_STYLE = "https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json";
+var CARTO_LABELS_LAYER_ID = "waterway_label";
+var OPEN_FREE_MAP_DARK_BASEMAP_STYLE = "https://tiles.openfreemap.org/styles/dark";
+var OPEN_FREE_MAP_LABELS_LAYER_ID = "highway_name_other";
+var BASEMAP_LABEL_LAYER_IDS = {
+  [CARTO_DARK_WITH_LABELS_BASEMAP_STYLE]: CARTO_LABELS_LAYER_ID,
+  [OPEN_FREE_MAP_DARK_BASEMAP_STYLE]: OPEN_FREE_MAP_LABELS_LAYER_ID
+};
+
 // src/geo/StacCompareMap/StacCompareMap.tsx
 import { jsx as jsx17, jsxs as jsxs14 } from "react/jsx-runtime";
 var MAP_PANEL_STYLE = {
@@ -1127,12 +1123,13 @@ var MAP_PANEL_STYLE = {
   width: "100%"
 };
 function StacCompareMap({
-  baseMapStyle,
+  baseMapStyle = CARTO_DARK_WITH_LABELS_BASEMAP_STYLE,
   initialViewState,
   leftLayerConfig,
   rightLayerConfig,
   className
 }) {
+  const resolvedBeforeLayerId = typeof baseMapStyle === "string" ? BASEMAP_LABEL_LAYER_IDS[baseMapStyle] : void 0;
   const instanceId = useId();
   const leftMapRef = useRef3(null);
   const rightMapRef = useRef3(null);
@@ -1174,7 +1171,7 @@ function StacCompareMap({
     };
   }, []);
   const mapProps = {
-    ...baseMapStyle && { mapStyle: baseMapStyle },
+    mapStyle: baseMapStyle,
     ...initialViewState && { initialViewState },
     style: MAP_PANEL_STYLE
   };
@@ -1189,7 +1186,14 @@ function StacCompareMap({
         children: [
           /* @__PURE__ */ jsx17(AttributionMapControl, {}),
           /* @__PURE__ */ jsx17(NavigationControl, { position: "top-left", showCompass: false }),
-          left.mapSource.tiles && /* @__PURE__ */ jsx17(Source, { id: leftSourceId, type: "raster", tiles: [left.mapSource.tiles], children: /* @__PURE__ */ jsx17(Layer, { id: leftLayerId, type: "raster" }) })
+          left.mapSource.tiles && /* @__PURE__ */ jsx17(Source, { id: leftSourceId, type: "raster", tiles: [left.mapSource.tiles], children: /* @__PURE__ */ jsx17(
+            Layer,
+            {
+              id: leftLayerId,
+              type: "raster",
+              ...resolvedBeforeLayerId && { beforeId: resolvedBeforeLayerId }
+            }
+          ) })
         ]
       }
     ),
@@ -1202,7 +1206,14 @@ function StacCompareMap({
         onLoad: () => setRightMapLoaded(true),
         children: [
           /* @__PURE__ */ jsx17(AttributionMapControl, {}),
-          right.mapSource.tiles && /* @__PURE__ */ jsx17(Source, { id: rightSourceId, type: "raster", tiles: [right.mapSource.tiles], children: /* @__PURE__ */ jsx17(Layer, { id: rightLayerId, type: "raster" }) })
+          right.mapSource.tiles && /* @__PURE__ */ jsx17(Source, { id: rightSourceId, type: "raster", tiles: [right.mapSource.tiles], children: /* @__PURE__ */ jsx17(
+            Layer,
+            {
+              id: rightLayerId,
+              type: "raster",
+              ...resolvedBeforeLayerId && { beforeId: resolvedBeforeLayerId }
+            }
+          ) })
         ]
       }
     ),
@@ -1222,10 +1233,11 @@ import {
 } from "react-map-gl/maplibre";
 import { jsx as jsx18, jsxs as jsxs15 } from "react/jsx-runtime";
 function StacSingleLayerMap({
-  baseMapStyle = NASA_BLUE_MARBLE_BASEMAP_STYLE,
+  baseMapStyle = CARTO_DARK_WITH_LABELS_BASEMAP_STYLE,
   initialViewState,
   layerConfig
 }) {
+  const resolvedBeforeLayerId = typeof baseMapStyle === "string" ? BASEMAP_LABEL_LAYER_IDS[baseMapStyle] : void 0;
   const instanceId = useId2();
   const sourceId = `${layerConfig.collectionId}-raster-source-${instanceId}`;
   const layerId = `${layerConfig.collectionId}-raster-layer-${instanceId}`;
@@ -1241,7 +1253,14 @@ function StacSingleLayerMap({
         children: [
           /* @__PURE__ */ jsx18(AttributionMapControl, {}),
           /* @__PURE__ */ jsx18(NavigationControl2, { position: "top-left", showCompass: false }),
-          mapSource.tiles && /* @__PURE__ */ jsx18(Source2, { id: sourceId, type: "raster", tiles: [mapSource.tiles], children: /* @__PURE__ */ jsx18(Layer2, { id: layerId, type: "raster" }) })
+          mapSource.tiles && /* @__PURE__ */ jsx18(Source2, { id: sourceId, type: "raster", tiles: [mapSource.tiles], children: /* @__PURE__ */ jsx18(
+            Layer2,
+            {
+              id: layerId,
+              type: "raster",
+              ...resolvedBeforeLayerId && { beforeId: resolvedBeforeLayerId }
+            }
+          ) })
         ]
       }
     ),
@@ -1251,6 +1270,9 @@ function StacSingleLayerMap({
 }
 export {
   Banner,
+  CARTO_DARK_BASEMAP_STYLE,
+  CARTO_DARK_WITH_LABELS_BASEMAP_STYLE,
+  CARTO_LABELS_LAYER_ID,
   Card,
   CardCTA,
   CardDetailed,
@@ -1262,6 +1284,8 @@ export {
   Legend,
   Link3 as Link,
   NASA_BLUE_MARBLE_BASEMAP_STYLE,
+  OPEN_FREE_MAP_DARK_BASEMAP_STYLE,
+  OPEN_FREE_MAP_LABELS_LAYER_ID,
   StacCompareMap,
   StacSingleLayerMap,
   Tag

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teamimpact/veda-ui-blocks",
-  "version": "0.1.0-beta.11",
+  "version": "0.1.0-beta.12",
   "description": "UI component library for VEDA-based portals, built on USWDS and React",
   "license": "MIT",
   "repository": {
@@ -67,7 +67,7 @@
     "storybook": "^10.2.17",
     "tsup": "^8.5.1",
     "typescript": "5.9.3",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.0"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts && pnpm run build:css",