@elabs-ai/components-maps 4.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manuel Reimitz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+<!-- brand-ui:gen:readme:start -->
+<!-- Generated by scripts/gen-package-readmes.mjs — do not edit inside these markers. -->
+
+# `@elabs-ai/components-maps`
+
+> MapLibre GL maps: MapCanvas, markers, popups, controls, routes, arcs, GeoJSON, clusters.
+
+Part of **brand-ui**, a source-owned, token-driven React component system.
+These packages are **private** and are not published to any registry — they are
+consumed from this workspace. See `docs/CONSUMING.md`.
+
+## Install
+
+Inside this monorepo the packages resolve as workspace dependencies:
+
+```json
+"@elabs-ai/components-maps": "workspace:*"
+```
+
+## Set up styling (do not skip)
+
+Components are Tailwind v4 classes backed by semantic tokens. Two lines in
+your CSS entry, or **everything renders unstyled** — the single most common
+mistake:
+
+```css
+@import "@elabs-ai/components-tokens/styles.css";
+@source "../node_modules/@elabs-ai/components-maps/dist";
+```
+
+The `@source` line is required because Tailwind ignores `node_modules`. Add
+one per brand-ui package you render. Then wrap your app once:
+
+```tsx
+import { ThemeProvider } from "@elabs-ai/components-tokens";
+
+<ThemeProvider defaultTheme="light">{children}</ThemeProvider>;
+```
+
+## This package specifically
+
+- `maplibre-gl` is a peer — it owns a WebGL context and global CSS.
+- No CSS import needed: `MapCanvas` pulls in MapLibre's stylesheet and the brand overrides itself.
+
+## What's in it
+
+12 exported components — including `MapArc`, `MapCanvas`, `MapClusterLayer`, `MapControls`, `MapGeoJSON`.
+
+Don't guess the API — ask the CLI:
+
+```bash
+pnpm add -D @elabs-ai/components-cli
+pnpm exec brand-ui search <query>   # find a component
+pnpm exec brand-ui docs <Name>      # its real props, from source
+```
+
+## Using an AI coding agent?
+
+For Claude Code, install the plugin from this repo's checkout:
+
+```
+/plugin marketplace add .
+/plugin install brand-ui
+```
+
+`brand-ui docs <Name>` returns intent, composition, state→token mappings and
+anti-patterns — tell your agent to run it instead of guessing a prop. The CLI
+also runs as an MCP server (`brand-ui mcp`).
+
+## Full guide
+
+Tailwind and Next.js wiring, per-package extras, agent enablement and a
+prompt for migrating an existing project: `docs/CONSUMING.md`.
+
+## License
+
+UNLICENSED — private.
+
+<!-- brand-ui:gen:readme:end -->
+
+---
+
+## Package detail
+
+Token-driven MapLibre GL map components for brand-ui: `MapCanvas` (theme-aware
+basemap), `MapMarker` (+ content/label/popup/tooltip parts), `MapPopup`,
+`MapControls`, `MapRoute`, `MapArc`, `MapGeoJSON`, `MapClusterLayer`.
+
+```tsx
+import { MapCanvas, MapControls, MapMarker, MapMarkerContent } from "@elabs-ai/components-maps";
+
+<div className="h-96">
+  <MapCanvas center={[13.4, 52.52]} zoom={11}>
+    <MapMarker longitude={13.4} latitude={52.52}>
+      <MapMarkerContent />
+    </MapMarker>
+    <MapControls />
+  </MapCanvas>
+</div>;
+```
+
+- The basemap flavor (light/dark) follows the active theme's own
+  `color-scheme` (`resolveThemeIsDark`), so a theme you authored yourself
+  resolves correctly too; pass `theme` to pin it.
+- Default layer paints (routes, arcs, clusters, GeoJSON fills) resolve
+  semantic tokens at runtime — WebGL can't read CSS variables — and re-resolve
+  on theme change.
+- `<MapCanvas>` imports MapLibre's CSS and the brand popup overrides itself.
+- MapLibre's attribution control is **disabled by default**. The default Carto
+  basemap serves ODbL-licensed OpenStreetMap data that requires the credit, so
+  either display it via `<AttributionPanel>`
+  (`@elabs-ai/components-ui`) somewhere the user can reach, or
+  re-enable the in-map control with `attributionControl={{ compact: true }}`
+  (it wins through the prop spread). `styles` / `blank` avoid the requirement
+  entirely by changing the tiles.
+- Use `blank` for tile-less data-viz canvases (choropleths, arcs, dot maps).
+
+## Attribution
+
+Adapted from [mapcn](https://github.com/AnmolSaini16/mapcn) (MIT License,
+© 2025 Anmoldeep Singh). `maplibre-gl` is BSD-3-Clause.

package/dist/index.css

@@ -0,0 +1,11 @@
+/* src/map-canvas/maps.css */
+.maplibregl-popup-content {
+  background: transparent;
+  box-shadow: none;
+  padding: 0;
+  border-radius: 0;
+}
+.maplibregl-popup-tip {
+  display: none;
+}
+/*# sourceMappingURL=index.css.map */

package/dist/index.css.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/map-canvas/maps.css"],"sourcesContent":["/*\n * MapLibre popup chrome reset — @elabs-ai/components-maps popups paint their own surface\n * (bg-popover, border, shadow), so MapLibre's white bubble + tip must not\n * render underneath. Imported by <MapCanvas> alongside maplibre-gl's CSS.\n */\n.maplibregl-popup-content {\n  background: transparent;\n  box-shadow: none;\n  padding: 0;\n  border-radius: 0;\n}\n\n.maplibregl-popup-tip {\n  display: none;\n}\n"],"mappings":";AAKA,CAAC;AACC,cAAY;AACZ,cAAY;AACZ,WAAS;AACT,iBAAe;AACjB;AAEA,CAAC;AACC,WAAS;AACX;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,442 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import MapLibreGL, { MarkerOptions, PopupOptions } from 'maplibre-gl';
+export { LngLatBoundsLike, LngLatLike, MapLayerMouseEvent, MapMouseEvent, MapOptions, ProjectionSpecification, StyleSpecification } from 'maplibre-gl';
+
+/** Light-or-dark flavor of the active basemap (derived from the brand theme). */
+type BasemapTheme = "light" | "dark";
+interface MapContextValue {
+    /** The live MapLibre map instance (`null` until the map has mounted). */
+    map: MapLibreGL.Map | null;
+    /** True once the map AND its style are fully loaded — gate layer operations on this. */
+    isLoaded: boolean;
+    /** Which basemap flavor is active. */
+    resolvedTheme: BasemapTheme;
+    /**
+     * Changes whenever the active brand theme changes. Layer components use it
+     * as a dependency key to re-resolve semantic token colors for WebGL paint.
+     */
+    themeKey: string;
+}
+/** Access the map instance + load state from any descendant of `<MapCanvas>`. */
+declare function useMap(): MapContextValue;
+
+/** Map viewport state. */
+interface MapViewport {
+    /** Center coordinates [longitude, latitude]. */
+    center: [number, number];
+    /** Zoom level. */
+    zoom: number;
+    /** Bearing (rotation) in degrees. */
+    bearing: number;
+    /** Pitch (tilt) in degrees. */
+    pitch: number;
+}
+type MapStyleOption = string | MapLibreGL.StyleSpecification;
+/** The imperative handle exposed by `<MapCanvas ref>`: the MapLibre map itself. */
+type MapCanvasRef = MapLibreGL.Map;
+type MapCanvasProps = {
+    children?: ReactNode;
+    /** Additional CSS classes for the map container. */
+    className?: string;
+    /**
+     * Basemap flavor. If not provided, it is derived from the active brand theme
+     * (`data-theme` + that theme's own `color-scheme`), then a `dark`/`light` root class,
+     * then the OS preference.
+     */
+    theme?: BasemapTheme;
+    /** Custom map styles for light and dark themes. Overrides the default Carto styles. */
+    styles?: {
+        light?: MapStyleOption;
+        dark?: MapStyleOption;
+    };
+    /**
+     * Use a transparent, tile-less basemap instead of the default Carto street
+     * basemap — a blank canvas. Used alone it renders nothing; add your own
+     * layers on top (`<MapGeoJSON>`, `<MapArc>`, markers, …). Ideal for data
+     * visualizations. Ignored when an explicit `styles` prop is provided.
+     */
+    blank?: boolean;
+    /** Map projection type. Use `{ type: "globe" }` for a 3D globe view. */
+    projection?: MapLibreGL.ProjectionSpecification;
+    /**
+     * Controlled viewport. When provided together with `onViewportChange`, the
+     * map becomes controlled and the viewport is driven by this prop.
+     */
+    viewport?: Partial<MapViewport>;
+    /**
+     * Callback fired continuously as the viewport changes (pan, zoom, rotate,
+     * pitch). Use standalone to observe changes, or with `viewport` for
+     * controlled mode.
+     */
+    onViewportChange?: (viewport: MapViewport) => void;
+    /** Show a loading overlay on the map (e.g. while the app fetches map data). */
+    loading?: boolean;
+} & Omit<MapLibreGL.MapOptions, "container" | "style">;
+/**
+ * The root map surface — a token/theme-aware MapLibre GL canvas. Compose the
+ * other `@elabs-ai/components-maps` components (markers, popups, controls, layers) as
+ * children; they reach the map through context (`useMap`).
+ *
+ * The ref exposes the raw MapLibre `Map` instance for imperative work
+ * (`flyTo`, `fitBounds`, …).
+ */
+declare const MapCanvas: react.ForwardRefExoticComponent<{
+    children?: ReactNode;
+    /** Additional CSS classes for the map container. */
+    className?: string;
+    /**
+     * Basemap flavor. If not provided, it is derived from the active brand theme
+     * (`data-theme` + that theme's own `color-scheme`), then a `dark`/`light` root class,
+     * then the OS preference.
+     */
+    theme?: BasemapTheme;
+    /** Custom map styles for light and dark themes. Overrides the default Carto styles. */
+    styles?: {
+        light?: MapStyleOption;
+        dark?: MapStyleOption;
+    };
+    /**
+     * Use a transparent, tile-less basemap instead of the default Carto street
+     * basemap — a blank canvas. Used alone it renders nothing; add your own
+     * layers on top (`<MapGeoJSON>`, `<MapArc>`, markers, …). Ideal for data
+     * visualizations. Ignored when an explicit `styles` prop is provided.
+     */
+    blank?: boolean;
+    /** Map projection type. Use `{ type: "globe" }` for a 3D globe view. */
+    projection?: MapLibreGL.ProjectionSpecification;
+    /**
+     * Controlled viewport. When provided together with `onViewportChange`, the
+     * map becomes controlled and the viewport is driven by this prop.
+     */
+    viewport?: Partial<MapViewport>;
+    /**
+     * Callback fired continuously as the viewport changes (pan, zoom, rotate,
+     * pitch). Use standalone to observe changes, or with `viewport` for
+     * controlled mode.
+     */
+    onViewportChange?: (viewport: MapViewport) => void;
+    /** Show a loading overlay on the map (e.g. while the app fetches map data). */
+    loading?: boolean;
+} & Omit<MapLibreGL.MapOptions, "container" | "style"> & react.RefAttributes<MapLibreGL.Map>>;
+
+type MapMarkerProps = {
+    /** Longitude coordinate for the marker position. */
+    longitude: number;
+    /** Latitude coordinate for the marker position. */
+    latitude: number;
+    /** Marker sub-components (MapMarkerContent, MapMarkerPopup, MapMarkerTooltip, MapMarkerLabel). */
+    children: ReactNode;
+    /** Callback when the marker is clicked. */
+    onClick?: (e: MouseEvent) => void;
+    /** Callback when the mouse enters the marker. */
+    onMouseEnter?: (e: MouseEvent) => void;
+    /** Callback when the mouse leaves the marker. */
+    onMouseLeave?: (e: MouseEvent) => void;
+    /** Callback when a drag starts (requires `draggable`). */
+    onDragStart?: (lngLat: {
+        lng: number;
+        lat: number;
+    }) => void;
+    /** Callback during a drag (requires `draggable`). */
+    onDrag?: (lngLat: {
+        lng: number;
+        lat: number;
+    }) => void;
+    /** Callback when a drag ends (requires `draggable`). */
+    onDragEnd?: (lngLat: {
+        lng: number;
+        lat: number;
+    }) => void;
+} & Omit<MarkerOptions, "element">;
+/**
+ * A marker anchored at a lng/lat. Compose the pieces you need:
+ * `MapMarkerContent` (the visual), `MapMarkerLabel`, `MapMarkerPopup` (opens
+ * on click) and `MapMarkerTooltip` (shows on hover).
+ */
+declare function MapMarker({ longitude, latitude, children, onClick, onMouseEnter, onMouseLeave, onDragStart, onDrag, onDragEnd, draggable, ...markerOptions }: MapMarkerProps): react.JSX.Element;
+interface MapMarkerContentProps {
+    /** Custom marker content. Defaults to a primary-colored dot. */
+    children?: ReactNode;
+    /** Additional CSS classes for the marker container. */
+    className?: string;
+}
+/** The marker's visual, portaled into the MapLibre marker element. */
+declare function MapMarkerContent({ children, className }: MapMarkerContentProps): react.ReactPortal;
+type MapMarkerPopupProps = {
+    /** Popup content. */
+    children: ReactNode;
+    /** Additional CSS classes for the popup container. */
+    className?: string;
+    /** Show a close button in the popup (default: false). */
+    closeButton?: boolean;
+} & Omit<PopupOptions, "className" | "closeButton">;
+/** A popup attached to the marker — MapLibre toggles it on marker click. */
+declare function MapMarkerPopup({ children, className, closeButton, ...popupOptions }: MapMarkerPopupProps): react.ReactPortal;
+type MapMarkerTooltipProps = {
+    /** Tooltip content. */
+    children: ReactNode;
+    /** Additional CSS classes for the tooltip container. */
+    className?: string;
+} & Omit<PopupOptions, "className" | "closeButton" | "closeOnClick">;
+/** A hover tooltip attached to the marker. */
+declare function MapMarkerTooltip({ children, className, ...popupOptions }: MapMarkerTooltipProps): react.ReactPortal;
+interface MapMarkerLabelProps {
+    /** Label text content. */
+    children: ReactNode;
+    /** Additional CSS classes for the label. */
+    className?: string;
+    /** Position of the label relative to the marker (default: "top"). */
+    position?: "top" | "bottom";
+}
+/**
+ * A small always-visible text label above or below the marker. Portaled into
+ * the marker element so it anchors to the marker whether composed as a sibling
+ * of `MapMarkerContent` or nested inside it (the three-theme sweep caught the
+ * sibling composition rendering the label against the map container instead).
+ */
+declare function MapMarkerLabel({ children, className, position }: MapMarkerLabelProps): react.ReactPortal;
+
+type MapPopupProps = {
+    /** Longitude coordinate for the popup position. */
+    longitude: number;
+    /** Latitude coordinate for the popup position. */
+    latitude: number;
+    /** Callback when the popup is closed. */
+    onClose?: () => void;
+    /** Popup content. */
+    children: ReactNode;
+    /** Additional CSS classes for the popup container. */
+    className?: string;
+    /** Show a close button in the popup (default: false). */
+    closeButton?: boolean;
+} & Omit<PopupOptions, "className" | "closeButton">;
+/**
+ * A standalone popup anchored at a lng/lat (not attached to a marker) —
+ * typically rendered conditionally from app state (e.g. after a layer click).
+ */
+declare function MapPopup({ longitude, latitude, onClose, children, className, closeButton, ...popupOptions }: MapPopupProps): react.ReactPortal;
+
+interface MapControlsProps {
+    /** Position of the controls on the map (default: "bottom-right"). */
+    position?: "top-left" | "top-right" | "bottom-left" | "bottom-right";
+    /** Show zoom in/out buttons (default: true). */
+    showZoom?: boolean;
+    /** Show a compass button to reset bearing/pitch (default: false). */
+    showCompass?: boolean;
+    /** Show a locate button to fly to the user's location (default: false). */
+    showLocate?: boolean;
+    /** Show a fullscreen toggle button (default: false). */
+    showFullscreen?: boolean;
+    /** Additional CSS classes for the controls container. */
+    className?: string;
+    /** Callback with user coordinates when located. */
+    onLocate?: (coords: {
+        longitude: number;
+        latitude: number;
+    }) => void;
+    /** Callback when geolocation fails or is denied. */
+    onLocateError?: (error: GeolocationPositionError) => void;
+}
+/** Branded zoom / compass / locate / fullscreen controls. Render inside `<MapCanvas>`. */
+declare function MapControls({ position, showZoom, showCompass, showLocate, showFullscreen, className, onLocate, onLocateError, }: MapControlsProps): react.JSX.Element;
+
+interface MapRouteProps {
+    /** Optional unique identifier for the route layer. */
+    id?: string;
+    /** Array of [longitude, latitude] coordinate pairs defining the route. */
+    coordinates: [number, number][];
+    /** Line color as a CSS color value. Defaults to the theme's `--primary` token. */
+    color?: string;
+    /** Line width in pixels (default: 3). */
+    width?: number;
+    /** Line opacity from 0 to 1 (default: 0.8). */
+    opacity?: number;
+    /** Dash pattern [dash length, gap length] for dashed lines. */
+    dashArray?: [number, number];
+    /** Callback when the route line is clicked. */
+    onClick?: () => void;
+    /** Callback when the mouse enters the route line. */
+    onMouseEnter?: () => void;
+    /** Callback when the mouse leaves the route line. */
+    onMouseLeave?: () => void;
+    /** Whether the route is interactive — shows a pointer cursor on hover (default: true). */
+    interactive?: boolean;
+}
+/** A GeoJSON line layer for routes/paths. Renders nothing itself — it draws on the map. */
+declare function MapRoute({ id: propId, coordinates, color, width, opacity, dashArray, onClick, onMouseEnter, onMouseLeave, interactive, }: MapRouteProps): null;
+
+/** A single arc to render inside `<MapArc data={...}>`. */
+type MapArcDatum = {
+    /** Unique identifier for this arc. Required for hover state tracking and event payloads. */
+    id: string | number;
+    /** Start coordinate as [longitude, latitude]. */
+    from: [number, number];
+    /** End coordinate as [longitude, latitude]. */
+    to: [number, number];
+};
+/** Event payload passed to MapArc interaction callbacks. */
+type MapArcEvent<T extends MapArcDatum = MapArcDatum> = {
+    /** The arc datum that was hovered or clicked. */
+    arc: T;
+    /** Longitude of the cursor at the time of the event. */
+    longitude: number;
+    /** Latitude of the cursor at the time of the event. */
+    latitude: number;
+    /** The underlying MapLibre mouse event for advanced use cases. */
+    originalEvent: MapLibreGL.MapMouseEvent;
+};
+type MapArcLinePaint = NonNullable<MapLibreGL.LineLayerSpecification["paint"]>;
+type MapArcLineLayout = NonNullable<MapLibreGL.LineLayerSpecification["layout"]>;
+type MapArcProps<T extends MapArcDatum = MapArcDatum> = {
+    /** Array of arcs to render. Each arc must have a unique `id`. */
+    data: T[];
+    /** Optional unique identifier prefix for the arc source/layers. Auto-generated if not provided. */
+    id?: string;
+    /**
+     * How far each arc bows away from a straight line. `0` renders straight
+     * lines; higher values bend further; negative values bend to the opposite
+     * side. Arcs cross the antimeridian via the shorter direction. (default: 0.2)
+     */
+    curvature?: number;
+    /** Number of samples used to render each curve. Higher = smoother. (default: 64) */
+    samples?: number;
+    /**
+     * MapLibre paint properties for the arc layer. Merged on top of theme-aware
+     * defaults (`line-color` = the `--primary` token, `line-width: 2`,
+     * `line-opacity: 0.85`). Any value can be a MapLibre expression for
+     * per-feature styling; every field on each arc datum (besides `from`/`to`)
+     * is exposed via `["get", ...]`.
+     */
+    paint?: MapArcLinePaint;
+    /** MapLibre layout properties for the arc layer. Defaults to rounded joins/caps. */
+    layout?: MapArcLineLayout;
+    /**
+     * Paint properties applied to the arc currently under the cursor. Each key
+     * is merged into `paint` as a `case` expression keyed on per-feature hover
+     * state, so only the hovered arc changes appearance.
+     */
+    hoverPaint?: MapArcLinePaint;
+    /** Callback when an arc is clicked. */
+    onClick?: (e: MapArcEvent<T>) => void;
+    /**
+     * Callback fired when the hovered arc changes. Receives the cursor's
+     * lng/lat at the moment of entry, and `null` when the cursor leaves the
+     * last hovered arc.
+     */
+    onHover?: (e: MapArcEvent<T> | null) => void;
+    /** Whether arcs respond to mouse events (default: true). */
+    interactive?: boolean;
+    /** Optional MapLibre layer id to insert the arc layers before (z-order control). */
+    beforeId?: string;
+};
+/**
+ * Curved great-circle-style arcs between coordinate pairs (flight paths,
+ * network links). Pairs well with `<MapCanvas blank projection={{ type: "globe" }}>`.
+ */
+declare function MapArc<T extends MapArcDatum = MapArcDatum>({ data, id: propId, curvature, samples, paint, layout, hoverPaint, onClick, onHover, interactive, beforeId, }: MapArcProps<T>): null;
+
+/** Pure geometry for `<MapArc>` — kept engine-free so it can be unit-tested. */
+/**
+ * Sample a quadratic Bézier between `from` and `to` in lng/lat space.
+ * `curvature` is how far the arc bows away from a straight line (0 = straight;
+ * negative bends to the opposite side). The destination longitude is unwrapped
+ * relative to the origin so arcs cross the antimeridian via the shorter
+ * great-circle direction — resulting longitudes may fall outside [-180, 180],
+ * which MapLibre renders correctly on the globe projection.
+ */
+declare function buildArcCoordinates(from: [number, number], to: [number, number], curvature: number, samples: number): [number, number][];
+
+type MapGeoJSONData<P extends GeoJSON.GeoJsonProperties = GeoJSON.GeoJsonProperties> = GeoJSON.FeatureCollection<GeoJSON.Geometry, P> | GeoJSON.Feature<GeoJSON.Geometry, P> | GeoJSON.Geometry | string;
+type MapFillPaint = NonNullable<MapLibreGL.FillLayerSpecification["paint"]>;
+type MapLinePaint = NonNullable<MapLibreGL.LineLayerSpecification["paint"]>;
+/** A rendered feature with strongly-typed `properties`. */
+type MapGeoJSONFeature<P extends GeoJSON.GeoJsonProperties = GeoJSON.GeoJsonProperties> = Omit<MapLibreGL.MapGeoJSONFeature, "properties"> & {
+    properties: P;
+};
+/** Event payload passed to MapGeoJSON interaction callbacks. */
+type MapGeoJSONEvent<P extends GeoJSON.GeoJsonProperties = GeoJSON.GeoJsonProperties> = {
+    /** The feature under the cursor, with its typed GeoJSON properties. */
+    feature: MapGeoJSONFeature<P>;
+    /** Longitude of the cursor at the time of the event. */
+    longitude: number;
+    /** Latitude of the cursor at the time of the event. */
+    latitude: number;
+    /** The underlying MapLibre mouse event for advanced use cases. */
+    originalEvent: MapLibreGL.MapLayerMouseEvent;
+};
+type MapGeoJSONProps<P extends GeoJSON.GeoJsonProperties = GeoJSON.GeoJsonProperties> = {
+    /** GeoJSON data (FeatureCollection, Feature, Geometry) or a URL to fetch it from. */
+    data: MapGeoJSONData<P>;
+    /** Optional unique identifier prefix for the source/layers. Auto-generated if not provided. */
+    id?: string;
+    /**
+     * Feature property to promote to the feature `id`. Required for hover
+     * feature-state (`fillHoverPaint`) and stable `onHover`/`onClick` payloads.
+     */
+    promoteId?: string;
+    /**
+     * Paint for the polygon fill layer. Merged on top of a theme-aware neutral
+     * default (the `--border` token — a mid neutral that reads on the page
+     * surface in every theme). Pass `false` to omit the fill layer entirely
+     * (e.g. outlines only).
+     */
+    fillPaint?: MapFillPaint | false;
+    /**
+     * Paint for the outline layer. Merged on top of a hairline default
+     * (`line-color` = the `--background` token, `line-width` = 0.5) for thin
+     * separators. Override `line-color` if your container differs, or pass
+     * `false` to omit the layer.
+     */
+    linePaint?: MapLinePaint | false;
+    /**
+     * Paint merged onto the fill layer for the feature under the cursor, applied
+     * as a `case` expression keyed on hover feature-state. Requires `promoteId`.
+     */
+    fillHoverPaint?: MapFillPaint;
+    /** Callback when a feature is clicked. */
+    onClick?: (e: MapGeoJSONEvent<P>) => void;
+    /** Callback fired when the hovered feature changes; `null` when the cursor leaves. */
+    onHover?: (e: MapGeoJSONEvent<P> | null) => void;
+    /** Whether features respond to mouse events (default: false). */
+    interactive?: boolean;
+    /** Optional MapLibre layer id to insert the layers before (z-order control). */
+    beforeId?: string;
+};
+/**
+ * Renders arbitrary GeoJSON as fill + outline layers on the map. Composes like
+ * `MapRoute` / `MapArc` — drop it inside `<MapCanvas>` (typically with `blank`)
+ * for choropleths and region/data maps. For full control over expressions and
+ * multiple layers, manage layers directly via `useMap()` instead.
+ */
+declare function MapGeoJSON<P extends GeoJSON.GeoJsonProperties = GeoJSON.GeoJsonProperties>({ data, id: propId, promoteId, fillPaint, linePaint, fillHoverPaint, onClick, onHover, interactive, beforeId, }: MapGeoJSONProps<P>): null;
+
+type MapClusterLayerProps<P extends GeoJSON.GeoJsonProperties = GeoJSON.GeoJsonProperties> = {
+    /** GeoJSON FeatureCollection data or a URL to fetch GeoJSON from. */
+    data: string | GeoJSON.FeatureCollection<GeoJSON.Point, P>;
+    /** Maximum zoom level to cluster points on (default: 14). */
+    clusterMaxZoom?: number;
+    /** Radius of each cluster when clustering points, in pixels (default: 50). */
+    clusterRadius?: number;
+    /**
+     * Colors for cluster circles: [small, medium, large] based on point count.
+     * Defaults to the theme's `--success`/`--warning`/`--destructive` tokens.
+     */
+    clusterColors?: [string, string, string];
+    /** Point-count thresholds for the color/size steps: [medium, large] (default: [100, 750]). */
+    clusterThresholds?: [number, number];
+    /** Color for unclustered individual points. Defaults to the theme's `--primary` token. */
+    pointColor?: string;
+    /** Callback when an unclustered point is clicked. */
+    onPointClick?: (feature: GeoJSON.Feature<GeoJSON.Point, P>, coordinates: [number, number]) => void;
+    /** Callback when a cluster is clicked. If not provided, zooms into the cluster. */
+    onClusterClick?: (clusterId: number, coordinates: [number, number], pointCount: number) => void;
+};
+/**
+ * Clustered point rendering for large point datasets. Cluster circles step
+ * through the status tokens (success → warning → destructive) as the point
+ * count grows; strokes and count labels use the page surface for contrast.
+ */
+declare function MapClusterLayer<P extends GeoJSON.GeoJsonProperties = GeoJSON.GeoJsonProperties>({ data, clusterMaxZoom, clusterRadius, clusterColors, clusterThresholds, pointColor, onPointClick, onClusterClick, }: MapClusterLayerProps<P>): null;
+
+export { type BasemapTheme, MapArc, type MapArcDatum, type MapArcEvent, type MapArcLineLayout, type MapArcLinePaint, type MapArcProps, MapCanvas, type MapCanvasProps, type MapCanvasRef, MapClusterLayer, type MapClusterLayerProps, type MapContextValue, MapControls, type MapControlsProps, type MapFillPaint, MapGeoJSON, type MapGeoJSONData, type MapGeoJSONEvent, type MapGeoJSONFeature, type MapGeoJSONProps, type MapLinePaint, MapMarker, MapMarkerContent, type MapMarkerContentProps, MapMarkerLabel, type MapMarkerLabelProps, MapMarkerPopup, type MapMarkerPopupProps, type MapMarkerProps, MapMarkerTooltip, type MapMarkerTooltipProps, MapPopup, type MapPopupProps, MapRoute, type MapRouteProps, type MapStyleOption, type MapViewport, buildArcCoordinates, useMap };