### Basic mapcn-svelte Map Component Usage in Svelte

Source: https://mapcn-svelte.vercel.app/docs/installation

Example of how to import and use the Map and MapControls components from mapcn-svelte within a Svelte application. It demonstrates setting the initial center and zoom level for the map.

```svelte
<script lang="ts">
  import { Map, MapControls } from "$lib/components/ui/map";
  import { Card } from "$lib/components/ui/card";
</script>

<Card class="h-[300px] overflow-hidden p-0">
  <Map center={[-74.006, 40.7128]} zoom={11}>
    <MapControls />
  </Map>
</Card>
```

--------------------------------

### Install mapcn-svelte Map Component

Source: https://mapcn-svelte.vercel.app/docs/installation

Command to add the map component to your project using npx. This command also installs `maplibre-gl` as a dependency.

```bash
npx shadcn-svelte@latest add https://mapcn-svelte.dev/r/map.json
```

--------------------------------

### Route Planning with Multiple Options (OSRM API)

Source: https://mapcn-svelte.vercel.app/docs/routes

Illustrates how to display multiple route options and allow user selection, fetching real driving directions from the OSRM API. Users can click on a route or use buttons to switch between them.

```svelte
<script>
  import { MapRoute } from '@mapcn/svelte';
  import { onMount } from 'svelte';

  let routes = [];
  let selectedRouteIndex = 0;

  onMount(async () => {
    const response = await fetch('https://router.project-osrm.org/route/v1/driving/13.404973,52.520008;13.410000,52.510000?overview=full&geometries=geojson');
    const data = await response.json();
    routes = data.routes.map(route => route.geometry.coordinates);
  });

  function selectRoute(index) {
    selectedRouteIndex = index;
  }
</script>

{#if routes.length > 0}
  <MapRoute coordinates={routes[selectedRouteIndex]} />
  <div>
    {#each routes as route, index}
      <button on:click={() => selectRoute(index)}>{index + 1}</button>
    {/each}
  </div>
{/if}
```

--------------------------------

### Basic Route Drawing with MapRoute

Source: https://mapcn-svelte.vercel.app/docs/routes

Demonstrates how to draw a basic route with numbered stop markers along the path using the MapRoute component. This is useful for displaying simple directions or trails.

```svelte
<script>
  import { MapRoute } from '@mapcn/svelte';
  let routeCoordinates = [
    { lat: 34.0522, lng: -118.2437 },
    { lat: 36.7783, lng: -119.4179 },
    { lat: 40.7128, lng: -74.0060 }
  ];
</script>

<MapRoute coordinates={routeCoordinates} />
```

--------------------------------

### MarkerTooltip Component

Source: https://mapcn-svelte.vercel.app/docs/api-reference

Renders a tooltip that appears on hover. It must be used inside `MapMarker` and extends MapLibre GL's PopupOptions, excluding 'className', 'closeButton', and 'closeOnClick'.

```APIDOC
## MarkerTooltip Component

### Description
Renders a tooltip that appears on hover. Must be used inside `MapMarker`.
Extends PopupOptions from MapLibre GL (excluding `className`, `closeButton`, and `closeOnClick`).

### Props

- **children** (`Snippet`) - Tooltip content.
- **className** (`string`) - Additional CSS classes for the tooltip container.
```

--------------------------------

### Accessing Map Instance with Svelte Context

Source: https://mapcn-svelte.vercel.app/docs/api-reference

Demonstrates how to access the MapLibre GL map instance and its loading state within a Svelte component using the `getContext` function. This is crucial for interacting with the map API directly.

```typescript
import { getContext } from "svelte";
import type MapLibreGL from "maplibre-gl";

const mapCtx = getContext({
  getMap: () => MapLibreGL.Map | null,
  isLoaded: () => boolean,
}("map");

const map = mapCtx.getMap();
const isLoaded = mapCtx.isLoaded();
```

--------------------------------

### Map Component API

Source: https://mapcn-svelte.vercel.app/docs/api-reference

The root container component that initializes MapLibre GL and provides context to child components. It automatically handles theme switching between light and dark modes.

```APIDOC
## Map Component API

### Description
The root container component that initializes MapLibre GL and provides context to child components. Automatically handles theme switching between light and dark modes.
Extends MapOptions from MapLibre GL (excluding `container` and `style`).

### Props

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```html
<Map theme="dark" styles={{ light: lightStyle, dark: darkStyle }}>
  <MapMarker longitude={...} latitude={...} />
  <MapControls />
</Map>
```

### Response
#### Success Response (200)
This component does not have a direct response, but it provides context to child components.

#### Response Example
N/A
```

--------------------------------

### MarkerContent Component API

Source: https://mapcn-svelte.vercel.app/docs/api-reference

Renders the visual content of a marker. Must be used inside `MapMarker`. If no children are provided, it renders a default blue dot marker.

```APIDOC
## MarkerContent Component API

### Description
Renders the visual content of a marker. Must be used inside `MapMarker`. If no children provided, renders a default blue dot marker.

### Props

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```html
<MapMarker longitude={...} latitude={...}>
  <MarkerContent className="my-custom-marker">
    <div>
      <h3>Location Name</h3>
      <p>Some details here...</p>
    </div>
  </MarkerContent>
</MapMarker>
```

### Response
#### Success Response (200)
This component renders content within a marker and does not have a direct response.

#### Response Example
N/A
```

--------------------------------

### Access Map Instance and Listen to Events in Svelte Child Component

Source: https://mapcn-svelte.vercel.app/docs/advanced-usage

This snippet demonstrates how to access the MapLibre GL map instance from a child Svelte component using `getContext` and set up event listeners with `onMount`. It allows for dynamic interaction with the map, such as logging click coordinates. Ensure the child component is rendered within the `<Map>` component.

```typescript
<script lang="ts">
	import { Map } from "$lib/components/ui/map";
	import MapLibreGL from "maplibre-gl";
	import { getContext } from "svelte";
	import { onMount } from "svelte";

	// For child components inside Map, use getContext
	function MapEventListener() {
		const mapCtx = getContext<{
			getMap: () => MapLibreGL.Map | null;
			isLoaded: () => boolean;
		}>("map");

		onMount(() => {
			const map = mapCtx.getMap();
			if (!map || !mapCtx.isLoaded()) return;

			const handleClick = (e: MapLibreGL.MapMouseEvent) => {
				console.log("Clicked at:", e.lngLat);
			};

			map.on("click", handleClick);
			return () => map.off("click", handleClick);
		});

		return null;
	}
</script>
	// Usage
	<Map center={[ -74, 40.7]} zoom={10}>
		<MapEventListener />
	</Map>

```

--------------------------------

### Map Component Structure

Source: https://mapcn-svelte.vercel.app/docs/api-reference

Illustrates the hierarchical structure of map components, including the root Map component and its children like MapMarker, MapPopup, MapControls, and MapRoute. This structure is essential for building interactive maps.

```svelte
<Map>
  <MapMarker longitude={...} latitude={...}>
    <MarkerContent>
      <MarkerLabel />
    </MarkerContent>
    <MarkerPopup />
    <MarkerTooltip />
  </MapMarker>

  <MapPopup longitude={...} latitude={...} />
  <MapControls />
  <MapRoute coordinates={...} />
  <MapClusterLayer data={...} />
</Map>
```

--------------------------------

### MarkerPopup Component

Source: https://mapcn-svelte.vercel.app/docs/api-reference

Renders a popup attached to a marker that opens on click. It extends MapLibre GL's PopupOptions but excludes 'className' and 'closeButton' to prevent style conflicts.

```APIDOC
## MarkerPopup Component

### Description
Renders a popup attached to the marker that opens on click. Must be used inside `MapMarker`.
Extends PopupOptions from MapLibre GL (excluding `className` and `closeButton`).

### Props

- **children** (`Snippet`) - Popup content.
- **className** (`string`) - Additional CSS classes for the popup container.
- **closeButton** (`boolean`) - Show a close button in the popup. Defaults to `false`.
```

--------------------------------

### MapMarker Component API

Source: https://mapcn-svelte.vercel.app/docs/api-reference

A container for marker-related components. Provides context for its children and handles marker positioning. Extends MarkerOptions from MapLibre GL (excluding `element`).

```APIDOC
## MapMarker Component API

### Description
A container for marker-related components. Provides context for its children and handles marker positioning.
Extends MarkerOptions from MapLibre GL (excluding `element`).

### Props

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```html
<Map>
  <MapMarker longitude={-74.006} latitude={40.7128} onClick={handleMarkerClick}>
    <MarkerContent>Custom Marker</MarkerContent>
  </MapMarker>
</Map>
```

### Response
#### Success Response (200)
This component renders a marker on the map and does not have a direct response.

#### Response Example
N/A
```

--------------------------------

### MapControls Component API

Source: https://mapcn-svelte.vercel.app/docs/api-reference

Renders map control buttons (zoom, compass, locate, fullscreen). Must be used inside the `Map` component.

```APIDOC
## MapControls Component API

### Description
Renders map control buttons (zoom, compass, locate, fullscreen). Must be used inside `Map`.

### Props

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```html
<Map>
  <MapControls position="top-left" showZoom={true} showLocate={true} />
</Map>
```

### Response
#### Success Response (200)
This component renders UI elements and does not have a direct response.

#### Response Example
N/A
```

--------------------------------

### MarkerLabel Component

Source: https://mapcn-svelte.vercel.app/docs/api-reference

Renders a text label above or below the marker. This component must be used inside `MarkerContent`.

```APIDOC
## MarkerLabel Component

### Description
Renders a text label above or below the marker. Must be used inside `MarkerContent`.

### Props

- **children** (`Snippet`) - Label text content.
- **className** (`string`) - Additional CSS classes for the label.
- **position** (`"top" | "bottom"`) - Position of the label relative to the marker. Defaults to `"top"`.
```

--------------------------------

### MapRoute Component

Source: https://mapcn-svelte.vercel.app/docs/api-reference

Renders a line/route on the map connecting coordinate points. It supports click and hover interactions for building route selection UIs and must be used inside `Map`.

```APIDOC
## MapRoute Component

### Description
Renders a line/route on the map connecting coordinate points. Must be used inside `Map`.
Supports click and hover interactions for building route selection UIs.

### Props

- **id** (`string`) - Optional unique identifier for the route layer. Auto-generated if not provided.
- **coordinates** (`[number, number][]`) - Array of [longitude, latitude] coordinate pairs.
- **color** (`string`) - Line color (CSS color value). Defaults to `"#4285F4"`.
- **width** (`number`) - Line width in pixels. Defaults to `3`.
- **opacity** (`number`) - Line opacity (0 to 1). Defaults to `0.8`.
- **dashArray** (`[number, number]`) - Dash pattern [dash length, gap length] for dashed lines.
- **onClick** (`() => void`) - Callback when the route line is clicked.
```

--------------------------------

### MapPopup Component

Source: https://mapcn-svelte.vercel.app/docs/api-reference

A standalone popup component that can be placed anywhere on the map without a marker. It must be used inside `Map` and extends MapLibre GL's PopupOptions.

```APIDOC
## MapPopup Component

### Description
A standalone popup component that can be placed anywhere on the map without a marker. Must be used inside `Map`.
Extends PopupOptions from MapLibre GL (excluding `className` and `closeButton`).

### Props

- **longitude** (`number`) - Longitude coordinate for popup position.
- **latitude** (`number`) - Latitude coordinate for popup position.
- **onClose** (`() => void`) - Callback when popup is closed.
- **children** (`Snippet`) - Popup content.
- **className** (`string`) - Additional CSS classes for the popup container.
- **closeButton** (`boolean`) - Show a close button in the popup. Defaults to `false`.
```

--------------------------------

### MapClusterLayer Component

Source: https://mapcn-svelte.vercel.app/docs/api-reference

Renders clustered point data using MapLibre GL's native clustering. It automatically groups nearby points into clusters that expand on click and must be used inside `Map`. Supports a generic type parameter for typed feature properties.

```APIDOC
## MapClusterLayer Component

### Description
Renders clustered point data using MapLibre GL's native clustering. Automatically groups nearby points into clusters that expand on click. Must be used inside `Map`.
Supports a generic type parameter for typed feature properties: `MapClusterLayer<MyProperties>`.

### Props

- **data** (`string | GeoJSON.FeatureCollection`) - GeoJSON FeatureCollection data or URL to fetch GeoJSON from.
- **clusterMaxZoom** (`number`) - Maximum zoom level to cluster points on. Defaults to `14`.
- **clusterRadius** (`number`) - Radius of each cluster when clustering points (in pixels). Defaults to `50`.
- **clusterColors** (`[string, string, string]`) - Colors for cluster circles: [small, medium, large] based on point count. Defaults to `["#51bbd6", "#f1f075", "#f28cb1"]`.
- **clusterThresholds** (`[number, number]`) - Point count thresholds for color/size steps: [medium, large]. Defaults to `[100, 750]`.
- **pointColor** (`string`) - Color for unclustered individual points. Defaults to `"#3b82f6"`.
- **onPointClick** (`(feature: GeoJSON.Feature, coordinates: [number, number]) => void`) - Callback when an unclustered point is clicked.
- **onClusterClick** (`(clusterId: number, coordinates: [number, number], pointCount: number) => void`) - Callback when a cluster is clicked. If not provided, zooms into the cluster.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.