@aiaiai-pt/design-system 0.51.2 → 0.52.0

package/components/MapCluster.svelte

@@ -11,14 +11,28 @@
     markers={[{ id: '1', lon: -9.14, lat: 38.74, label: 'HQ' }]}
     onclick={(marker) => goto(`/equipment/${marker.id}`)}
   />
+
+  A marker with `pin` text is drawn as a labelled pin (a price, a time) from
+  the --map-pin-* tokens; `active: true` uses the active pin style, and the
+  marker whose popup is open is drawn active too.
+
+  @example
+  <MapCluster
+    markers={[{ id: 'h1', lon: -9.14, lat: 38.71, label: 'Hotel Lis', pin: '€182', active: true }]}
+    tileSource={{ type: 'osm', tone: 'muted' }}
+    {popup}
+  />
 -->
 <script>
+  import { tick } from 'svelte';
   import { fromLonLat } from 'ol/proj.js';
   import { boundingExtent } from 'ol/extent.js';
-  import { createTileLayer, createMapStyles, createOverlayLayers, clusterTooltipLabel, watchTheme, renderMapError } from './map-utils.js';
+  import { createTileLayer, createMapStyles, createOverlayLayers, clusterFeatureStyle, clusterTooltipLabel, popupCenter, watchTheme, renderMapError } from './map-utils.js';
 
   let {
-    /** @type {{ id: string, lon: number, lat: number, label?: string, [key: string]: any }[]} */
+    /** @type {{ id: string, lon: number, lat: number, label?: string, pin?: string, active?: boolean, [key: string]: any }[]}
+     *  `pin`: text drawn as the marker (a price, a time). `active`: draw
+     *  that pin in the active style (chosen, saved, current). */
     markers = [],
     /** @type {[number, number] | undefined} — initial center [lon, lat].
      *  Omit to auto-FIT the markers' extent (the right default for "show
@@ -76,6 +90,14 @@
   let _vectorSource = $state();
   /** @type {any} — Cluster source */
   let _clusterSource = $state();
+  /** @type {any} — Cluster vector layer */
+  let _clusterLayer = $state();
+
+  // The marker whose popup is open is drawn active: restyle on change.
+  $effect(() => {
+    void selected;
+    _clusterLayer?.changed();
+  });
   /** @type {any} — shared style factory (set at mount, consumed by the
    *  overlay owner effect) */
   let _styles = $state();
@@ -196,11 +218,9 @@
 
       const clusterLayer = new VectorLayer({
         source: clusterSource,
-        style: (feature) => {
-          const size = feature.get('features')?.length ?? 1;
-          return styles.cluster(size);
-        },
+        style: (feature) => clusterFeatureStyle(feature, styles, selected?.id),
       });
+      _clusterLayer = clusterLayer;
 
       // Tooltip overlay
       const tooltipEl = document.createElement('div');
@@ -312,11 +332,19 @@
           selected = data;
           if (coords) {
             _popupOverlay?.setPosition(coords);
-            // Fly TO the clicked marker: animate the view so the marker (and its
-            // anchored popup) is centred — a clear "the map moved to what I
-            // tapped" gesture, not a subtle edge-nudge. The small ficha-resumo
-            // card opens above the now-centred marker and stays in view.
-            map?.getView().animate({ center: coords, duration: 400 });
+            // Fly TO the clicked marker: animate the view so the marker and
+            // its anchored popup are centred together — a clear "the map moved
+            // to what I tapped" gesture. Measured after the snippet renders, so
+            // a tall card is not cut off at the top of a short map.
+            void tick().then(() => {
+              const view = map?.getView();
+              const height = map?.getSize()?.[1] ?? 0;
+              if (!view) return;
+              view.animate({
+                center: popupCenter(coords, popupEl?.offsetHeight ?? 0, height, view.getResolution() ?? 0),
+                duration: 400,
+              });
+            });
           }
         } else {
           onclick?.(data);
@@ -372,6 +400,13 @@
         styles.refresh();
         clusterSource.changed();
       });
+      // Pins are drawn on canvas with the token font. If the web font was
+      // still loading, redraw them once it is ready.
+      document.fonts?.ready.then(() => {
+        if (disposed) return;
+        styles.refresh();
+        clusterSource.changed();
+      });
     } catch (err) { renderMapError(container, 'MapCluster', /** @type {Error} */ (err)); } })();
 
     // Escape closes an open popup (keyboard dismissal).
@@ -420,6 +455,12 @@
     border-radius: inherit;
   }
 
+  /* tileSource.tone 'muted': the tile layer has its own canvas (see
+     tileLayerClass), so only the basemap is filtered. */
+  .map-cluster :global(.map-tiles-muted) {
+    filter: var(--map-tiles-muted-filter);
+  }
+
   /* Overlay element wrapper — OL owns its position (inline transform); this
      just lifts it above the map controls. The card chrome is the consumer's
      MapPopup. */

package/components/MapCluster.svelte.d.ts

@@ -16,6 +16,17 @@ type MapCluster = {
  *   markers={[{ id: '1', lon: -9.14, lat: 38.74, label: 'HQ' }]}
  *   onclick={(marker) => goto(`/equipment/${marker.id}`)}
  * />
+ *
+ * A marker with `pin` text is drawn as a labelled pin (a price, a time) from
+ * the --map-pin-* tokens; `active: true` uses the active pin style, and the
+ * marker whose popup is open is drawn active too.
+ *
+ * @example
+ * <MapCluster
+ *   markers={[{ id: 'h1', lon: -9.14, lat: 38.71, label: 'Hotel Lis', pin: '€182', active: true }]}
+ *   tileSource={{ type: 'osm', tone: 'muted' }}
+ *   {popup}
+ * />
  */
 declare const MapCluster: import("svelte").Component<{
     markers?: any[];

package/components/MapDisplay.svelte

@@ -182,4 +182,9 @@
   .map-display :global(.ol-viewport) {
     border-radius: inherit;
   }
+
+  /* tileSource.tone 'muted': only the basemap's own canvas is filtered. */
+  .map-display :global(.map-tiles-muted) {
+    filter: var(--map-tiles-muted-filter);
+  }
 </style>

package/components/MapHeatmap.svelte

@@ -208,4 +208,9 @@
   .map-heatmap :global(.ol-viewport) {
     border-radius: inherit;
   }
+
+  /* tileSource.tone 'muted': only the basemap's own canvas is filtered. */
+  .map-heatmap :global(.map-tiles-muted) {
+    filter: var(--map-tiles-muted-filter);
+  }
 </style>

package/components/MapPicker.svelte

@@ -397,6 +397,11 @@
     border-radius: inherit;
   }
 
+  /* tileSource.tone 'muted': only the basemap's own canvas is filtered. */
+  .map-picker-canvas :global(.map-tiles-muted) {
+    filter: var(--map-tiles-muted-filter);
+  }
+
   .map-picker-canvas.map-picker-error {
     border-color: var(--input-error-border-color);
   }

package/components/map-utils.d.ts

@@ -3,11 +3,25 @@
  * Not exported from index.js — internal to map components only.
  */
 /**
- * @typedef {{ type: 'osm' }} OsmSource
- * @typedef {{ type: 'xyz', url: string, attributions?: string, maxZoom?: number }} XyzSource
- * @typedef {{ type: 'stadia', layer: string, retina?: boolean, apiKey?: string }} StadiaSource
+ * @typedef {{ tone?: 'muted' }} TileTone — `tone: 'muted'` greys the
+ *   basemap (and darkens it in the dark scheme) through
+ *   `--map-tiles-muted-filter`, so markers and routes carry the colour. It
+ *   works with any source, including keyless OSM.
+ * @typedef {{ type: 'osm' } & TileTone} OsmSource
+ * @typedef {{ type: 'xyz', url: string, attributions?: string, maxZoom?: number } & TileTone} XyzSource
+ * @typedef {{ type: 'stadia', layer: string, retina?: boolean, apiKey?: string } & TileTone} StadiaSource
  * @typedef {OsmSource | XyzSource | StadiaSource} TileSourceConfig
  */
+/**
+ * The tile layer's class. OpenLayers draws consecutive layers that share a
+ * class on one canvas, so a distinct class gives the tiles a canvas of their
+ * own. The map components filter that canvas with `--map-tiles-muted-filter`;
+ * the markers and overlays above it stay at full colour.
+ *
+ * @param {TileSourceConfig} config
+ * @returns {string}
+ */
+export function tileLayerClass(config: TileSourceConfig): string;
 /**
  * Creates an OL tile layer from a config object.
  *
@@ -20,6 +34,9 @@ export function createTileLayer(config: TileSourceConfig): Promise<import("ol/la
  * @property {import('ol/style/Style.js').default} marker
  * @property {import('ol/style/Style.js').default} polygon
  * @property {(size: number) => import('ol/style/Style.js').default} cluster
+ * @property {(text: string, active?: boolean) => import('ol/style/Style.js').default} pin
+ *   — a label drawn as the marker itself (a price, a time, a short name),
+ *   from the --map-pin-* tokens; `active` uses the --map-pin-active-* set
  * @property {() => void} refresh — re-read CSS tokens, mutate styles in place
  */
 /**
@@ -116,6 +133,36 @@ export function geoStylerToFlat(style: any): OverlayLayerStyle;
  * @returns {Promise<import('ol/layer/Vector.js').default[]>}
  */
 export function createOverlayLayers(defs: OverlayLayerDef[], styles: import("./map-utils.js").MapStyles): Promise<import("ol/layer/Vector.js").default[]>;
+/**
+ * Decide how one feature of the cluster layer is drawn.
+ *
+ * A cluster of one is its marker: a pin with the marker's `pin` text when it
+ * has one (active when the marker says `active` or is the one whose popup is
+ * open), otherwise the plain marker dot. A cluster of many shows its count.
+ *
+ * @param {{ get: (key: string) => any }} feature — a Cluster-source feature
+ * @param {Pick<MapStyles, 'marker' | 'cluster' | 'pin'>} styles
+ * @param {string | number | null | undefined} [selectedId] — id of the
+ *   marker whose popup is open
+ * @returns {import('ol/style/Style.js').default}
+ */
+export function clusterFeatureStyle(feature: {
+    get: (key: string) => any;
+}, styles: Pick<MapStyles, "marker" | "cluster" | "pin">, selectedId?: string | number | null | undefined): import("ol/style/Style.js").default;
+/**
+ * Where to centre the view so a marker and the popup above it are centred
+ * together: the marker sits below the middle by half the popup's height, so
+ * a card taller than half the map is not cut off at the top. The shift is
+ * capped so the marker stays `margin` pixels inside the bottom edge.
+ *
+ * @param {number[]} coords — marker coordinate in view projection (y grows north)
+ * @param {number} popupHeight — popup element height, px
+ * @param {number} mapHeight — map viewport height, px
+ * @param {number} resolution — view resolution, map units per px
+ * @param {number} [margin] — px kept between marker and bottom edge
+ * @returns {number[]}
+ */
+export function popupCenter(coords: number[], popupHeight: number, mapHeight: number, resolution: number, margin?: number): number[];
 /**
  * Decide the hover-tooltip text for a feature under the pointer.
  *
@@ -161,26 +208,40 @@ export function pointInRings(lonLat: [number, number], rings: number[][][]): boo
  * @returns {Promise<import('ol/layer/Vector.js').default | null>}
  */
 export function createBoundaryLayer(rings: number[][][], el: Element): Promise<import("ol/layer/Vector.js").default | null>;
+/**
+ * — `tone: 'muted'` greys the
+ *   basemap (and darkens it in the dark scheme) through
+ *   `--map-tiles-muted-filter`, so markers and routes carry the colour. It
+ *   works with any source, including keyless OSM.
+ */
+export type TileTone = {
+    tone?: "muted";
+};
 export type OsmSource = {
     type: "osm";
-};
+} & TileTone;
 export type XyzSource = {
     type: "xyz";
     url: string;
     attributions?: string;
     maxZoom?: number;
-};
+} & TileTone;
 export type StadiaSource = {
     type: "stadia";
     layer: string;
     retina?: boolean;
     apiKey?: string;
-};
+} & TileTone;
 export type TileSourceConfig = OsmSource | XyzSource | StadiaSource;
 export type MapStyles = {
     marker: import("ol/style/Style.js").default;
     polygon: import("ol/style/Style.js").default;
     cluster: (size: number) => import("ol/style/Style.js").default;
+    /**
+     *   — a label drawn as the marker itself (a price, a time, a short name),
+     *   from the --map-pin-* tokens; `active` uses the --map-pin-active-* set
+     */
+    pin: (text: string, active?: boolean) => import("ol/style/Style.js").default;
     /**
      * — re-read CSS tokens, mutate styles in place
      */

package/components/map-utils.js

@@ -4,12 +4,29 @@
  */
 
 /**
- * @typedef {{ type: 'osm' }} OsmSource
- * @typedef {{ type: 'xyz', url: string, attributions?: string, maxZoom?: number }} XyzSource
- * @typedef {{ type: 'stadia', layer: string, retina?: boolean, apiKey?: string }} StadiaSource
+ * @typedef {{ tone?: 'muted' }} TileTone — `tone: 'muted'` greys the
+ *   basemap (and darkens it in the dark scheme) through
+ *   `--map-tiles-muted-filter`, so markers and routes carry the colour. It
+ *   works with any source, including keyless OSM.
+ * @typedef {{ type: 'osm' } & TileTone} OsmSource
+ * @typedef {{ type: 'xyz', url: string, attributions?: string, maxZoom?: number } & TileTone} XyzSource
+ * @typedef {{ type: 'stadia', layer: string, retina?: boolean, apiKey?: string } & TileTone} StadiaSource
  * @typedef {OsmSource | XyzSource | StadiaSource} TileSourceConfig
  */
 
+/**
+ * The tile layer's class. OpenLayers draws consecutive layers that share a
+ * class on one canvas, so a distinct class gives the tiles a canvas of their
+ * own. The map components filter that canvas with `--map-tiles-muted-filter`;
+ * the markers and overlays above it stay at full colour.
+ *
+ * @param {TileSourceConfig} config
+ * @returns {string}
+ */
+export function tileLayerClass(config) {
+  return config?.tone === "muted" ? "ol-layer map-tiles-muted" : "ol-layer";
+}
+
 /**
  * Creates an OL tile layer from a config object.
  *
@@ -18,10 +35,12 @@
  */
 export async function createTileLayer(config) {
   const { default: TileLayer } = await import("ol/layer/Tile.js");
+  const className = tileLayerClass(config);
 
   if (config.type === "stadia") {
     const { default: StadiaMaps } = await import("ol/source/StadiaMaps.js");
     return new TileLayer({
+      className,
       source: new StadiaMaps({
         layer: config.layer,
         retina: config.retina ?? true,
@@ -33,6 +52,7 @@ export async function createTileLayer(config) {
   if (config.type === "xyz") {
     const { default: XYZ } = await import("ol/source/XYZ.js");
     return new TileLayer({
+      className,
       source: new XYZ({
         url: config.url,
         attributions: config.attributions,
@@ -43,7 +63,7 @@ export async function createTileLayer(config) {
   }
 
   const { default: OSM } = await import("ol/source/OSM.js");
-  return new TileLayer({ source: new OSM() });
+  return new TileLayer({ className, source: new OSM() });
 }
 
 // ─── Theme-Reactive Style Factory ────────────────────────────────
@@ -53,6 +73,9 @@ export async function createTileLayer(config) {
  * @property {import('ol/style/Style.js').default} marker
  * @property {import('ol/style/Style.js').default} polygon
  * @property {(size: number) => import('ol/style/Style.js').default} cluster
+ * @property {(text: string, active?: boolean) => import('ol/style/Style.js').default} pin
+ *   — a label drawn as the marker itself (a price, a time, a short name),
+ *   from the --map-pin-* tokens; `active` uses the --map-pin-active-* set
  * @property {() => void} refresh — re-read CSS tokens, mutate styles in place
  */
 
@@ -71,12 +94,14 @@ export async function createMapStyles(el) {
     { default: Fill },
     { default: Stroke },
     { default: Text },
+    { default: Icon },
   ] = await Promise.all([
     import("ol/style/Style.js"),
     import("ol/style/Circle.js"),
     import("ol/style/Fill.js"),
     import("ol/style/Stroke.js"),
     import("ol/style/Text.js"),
+    import("ol/style/Icon.js"),
   ]);
 
   // Mutable fill/stroke refs — mutated in-place on refresh()
@@ -106,6 +131,10 @@ export async function createMapStyles(el) {
 
   /** @type {Map<string, import('ol/style/Style.js').default>} */
   const clusterCache = new Map();
+  /** @type {Map<string, import('ol/style/Style.js').default>} */
+  const pinCache = new Map();
+  /** @type {Record<string, any>} — pin tokens, read in readTokens() */
+  let pinTokens = {};
 
   function readTokens() {
     markerFillObj.setColor(cssVar(el, "--map-marker-fill", "#ff6b35"));
@@ -123,6 +152,23 @@ export async function createMapStyles(el) {
     const font = cssVar(el, "--map-cluster-font", "monospace");
     const fontSize = cssVar(el, "--map-cluster-font-size", "12px");
     clusterFontStr = `600 ${fontSize} ${font}`;
+    pinTokens = {
+      bg: resolveColor(el, cssVar(el, "--map-pin-bg", "#fff")),
+      text: resolveColor(el, cssVar(el, "--map-pin-text", "#2c2825")),
+      border: resolveColor(el, cssVar(el, "--map-pin-border-color", "#999")),
+      activeBg: resolveColor(el, cssVar(el, "--map-pin-active-bg", "#2c2825")),
+      activeText: resolveColor(el, cssVar(el, "--map-pin-active-text", "#fff")),
+      activeBorder: resolveColor(
+        el,
+        cssVar(el, "--map-pin-active-border-color", "#2c2825"),
+      ),
+      borderWidth: cssPx(el, "--map-pin-border-width", 1),
+      radius: cssPx(el, "--map-pin-radius", 999),
+      paddingX: cssPx(el, "--map-pin-padding-x", 8),
+      paddingY: cssPx(el, "--map-pin-padding-y", 4),
+      fontSize: cssPx(el, "--map-pin-font-size", 12),
+      font: `${cssVar(el, "--map-pin-font-weight", "600")} ${cssPx(el, "--map-pin-font-size", 12)}px ${cssVar(el, "--map-pin-font", "sans-serif")}`,
+    };
 
     // Rebuild marker image with new radius (CircleStyle radius is immutable)
     marker.setImage(
@@ -164,12 +210,74 @@ export async function createMapStyles(el) {
     return style;
   }
 
+  /**
+   * A pill with the text inside, drawn on a canvas at the device's pixel
+   * ratio and used as the marker image, so it hit-tests, clusters and
+   * themes like any marker.
+   *
+   * @param {string} text
+   * @param {boolean} [active]
+   */
+  function pin(text, active = false) {
+    const key = `${active ? "a" : "n"}|${text}`;
+    const cached = pinCache.get(key);
+    if (cached) return cached;
+
+    const t = pinTokens;
+    const ratio = window.devicePixelRatio || 1;
+    const canvas = document.createElement("canvas");
+    const measure = canvas.getContext("2d");
+    if (!measure) return marker;
+    measure.font = t.font;
+    const width = Math.ceil(
+      measure.measureText(text).width + 2 * (t.paddingX + t.borderWidth),
+    );
+    const height = Math.ceil(t.fontSize + 2 * (t.paddingY + t.borderWidth));
+    canvas.width = width * ratio;
+    canvas.height = height * ratio;
+
+    const ctx = /** @type {CanvasRenderingContext2D} */ (
+      canvas.getContext("2d")
+    );
+    ctx.scale(ratio, ratio);
+    const inset = t.borderWidth / 2;
+    ctx.beginPath();
+    ctx.roundRect(
+      inset,
+      inset,
+      width - t.borderWidth,
+      height - t.borderWidth,
+      Math.min(t.radius, height / 2),
+    );
+    ctx.fillStyle = active ? t.activeBg : t.bg;
+    ctx.fill();
+    if (t.borderWidth > 0) {
+      ctx.lineWidth = t.borderWidth;
+      ctx.strokeStyle = active ? t.activeBorder : t.border;
+      ctx.stroke();
+    }
+    ctx.font = t.font;
+    ctx.fillStyle = active ? t.activeText : t.text;
+    ctx.textAlign = "center";
+    ctx.textBaseline = "middle";
+    ctx.fillText(text, width / 2, height / 2);
+
+    const style = new Style({
+      image: new Icon({ img: canvas, scale: 1 / ratio }),
+      // Active pins draw above the rest; pins above plain markers.
+      zIndex: active ? 2 : 1,
+    });
+    pinCache.set(key, style);
+    return style;
+  }
+
   function refresh() {
     readTokens();
     clusterCache.clear(); // cluster styles must be rebuilt with new colors
+    pinCache.clear();
   }
 
-  return { marker, polygon, cluster, refresh };
+  return { marker, polygon, cluster, pin, refresh };
 }
 
 // ─── Theme Watcher ───────────────────────────────────────────────
@@ -489,6 +597,53 @@ export async function createOverlayLayers(defs, styles) {
     });
 }
 
+// ─── Clustered marker style ──────────────────────────────────────
+
+/**
+ * Decide how one feature of the cluster layer is drawn.
+ *
+ * A cluster of one is its marker: a pin with the marker's `pin` text when it
+ * has one (active when the marker says `active` or is the one whose popup is
+ * open), otherwise the plain marker dot. A cluster of many shows its count.
+ *
+ * @param {{ get: (key: string) => any }} feature — a Cluster-source feature
+ * @param {Pick<MapStyles, 'marker' | 'cluster' | 'pin'>} styles
+ * @param {string | number | null | undefined} [selectedId] — id of the
+ *   marker whose popup is open
+ * @returns {import('ol/style/Style.js').default}
+ */
+export function clusterFeatureStyle(feature, styles, selectedId) {
+  const members = feature.get("features");
+  if (!members?.length) return styles.marker;
+  if (members.length > 1) return styles.cluster(members.length);
+  const data = members[0].get("markerData");
+  const text = data?.pin == null ? "" : String(data.pin);
+  if (!text) return styles.marker;
+  const active =
+    data.active === true || (selectedId != null && data.id === selectedId);
+  return styles.pin(text, active);
+}
+
+// ─── Popup framing ───────────────────────────────────────────────
+
+/**
+ * Where to centre the view so a marker and the popup above it are centred
+ * together: the marker sits below the middle by half the popup's height, so
+ * a card taller than half the map is not cut off at the top. The shift is
+ * capped so the marker stays `margin` pixels inside the bottom edge.
+ *
+ * @param {number[]} coords — marker coordinate in view projection (y grows north)
+ * @param {number} popupHeight — popup element height, px
+ * @param {number} mapHeight — map viewport height, px
+ * @param {number} resolution — view resolution, map units per px
+ * @param {number} [margin] — px kept between marker and bottom edge
+ * @returns {number[]}
+ */
+export function popupCenter(coords, popupHeight, mapHeight, resolution, margin = 24) {
+  const shift = Math.max(0, Math.min(popupHeight / 2, mapHeight / 2 - margin));
+  return [coords[0], coords[1] + shift * resolution];
+}
+
 // ─── Hover tooltip label ─────────────────────────────────────────
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiaiai-pt/design-system",
-  "version": "0.51.2",
+  "version": "0.52.0",
   "description": "Design system tokens and Svelte components for aiaiai products",
   "license": "MIT",
   "type": "module",

package/tokens/components.css

@@ -859,6 +859,26 @@
   --map-marker-stroke: var(--color-surface);
   --map-marker-stroke-width: var(--border-width-thick);
 
+  /* Pin: a marker drawn as a label (marker.pin: a price, a time) */
+  --map-pin-bg: var(--color-surface);
+  --map-pin-text: var(--color-text);
+  --map-pin-border-color: var(--color-border-strong);
+  --map-pin-border-width: var(--border-width);
+  --map-pin-radius: var(--radius-pill);
+  --map-pin-padding-x: var(--space-sm);
+  --map-pin-padding-y: var(--space-xs);
+  --map-pin-font: var(--type-label-font);
+  --map-pin-font-size: var(--type-label-size);
+  --map-pin-font-weight: var(--type-heading-weight);
+  /* Active pin (marker.active, or the marker whose popup is open) */
+  --map-pin-active-bg: var(--color-text);
+  --map-pin-active-text: var(--color-surface);
+  --map-pin-active-border-color: var(--color-text);
+
+  /* Basemap tone (tileSource.tone: 'muted'): quiet tiles so markers and
+     routes carry the colour. Redefined for the dark scheme below. */
+  --map-tiles-muted-filter: grayscale(1) contrast(0.7) brightness(1.08);
+
   /* Cluster */
   --map-cluster-radius: var(--space-md);
   --map-cluster-fill: var(--color-accent);
@@ -995,3 +1015,8 @@
   --focus-ring-offset: var(--border-width-thick);
   --focus-ring-color: var(--color-accent);
 }
+
+/* Dark scheme: the muted basemap inverts to a dark ground. */
+:root[data-scheme="dark"] {
+  --map-tiles-muted-filter: grayscale(1) invert(1) contrast(0.8) brightness(0.9);
+}