DOCSEARCHbyAlgolia
Submit Docs

mapcn

repository·main·Indexed 27 days ago

https://github.com/anmolsaini16/mapcn

A library of customizable React map components built on MapLibre GL, designed for seamless integration with Tailwind CSS and shadcn/ui. It features theme-aware components, markers, popups, route drawing, and built-in controls. The library includes specialized blocks such as an Analytics Map, Delivery Tracker with OSRM routing support, and an Uptime Monitor for network health visualization.

Tokens
2K
Snippets
5
Records
8
Agent score
95%

What's inside mapcn

  1. Overview of mapcn features

    main

    mapcn provides free, open-source, and customizable map components for React. It is designed for zero-configuration setup and is built on MapLibre GL, styled with Tailwind CSS, and is compatible with shadcn/ui patterns.

    Key capabilities include:

    • Theme-aware: Automatically adapts to light and dark modes.
    • Composable UI: Declarative components for building complex map interfaces.
    • Markers & Popups: Rich system for markers, popups, tooltips, and labels.
    • Routes: Ability to draw routes and paths on maps.
    • Controls: Built-in zoom, compass, locate, and fullscreen controls.

  2. Basemap Terms of Service and Alternatives

    main

    By default, mapcn uses CARTO Basemaps (based on OpenStreetMap data).

    Usage Restrictions:

    • Commercial use: Requires a CARTO Enterprise license.
    • Non-commercial use: Free for CARTO grantees under their specific basemap terms.

    Alternatives: If you do not wish to use CARTO, you can switch to any MapLibre-compatible tile provider, such as OpenStreetMap tiles, MapTiler, or Stadia Maps.

  3. Generate a routing URL with buildRouteUrl

    main

    The buildRouteUrl function generates a URL for a routing service (defaulting to OSRM) that returns GeoJSON route geometry. You can use this to fetch route data between two points.

    To use a different routing service, provide a function that returns a URL responding with GeoJSON route geometry.

    export function buildRouteUrl(
  from: { lng: number; lat: number },
  to: { lng: number; lat: number },
) {
  return `https://router.project-osrm.org/route/v1/driving/${from.lng},${from.lat};${to.lng},${to.lat}?overview=full&geometries=geojson`;
}

  4. Define Uptime Monitor data structures

    main

    When implementing or extending the Uptime Monitor block, use the following types and interfaces to ensure data consistency:

    • EdgeStatus: A union type representing the health of a node: "operational", "degraded", or "down".
    • EdgeNode: Represents an individual point of presence in the network.
    • NetworkSummary: Represents the aggregated health status of the entire network.

    Use the getNetworkSummary function to derive a NetworkSummary from an array of EdgeNode objects.

    export type EdgeStatus = "operational" | "degraded" | "down";

export interface EdgeNode {
  id: string;
  city: string;
  region: string;
  lng: number;
  lat: number;
  status: EdgeStatus;
  latency: number;
  uptime: number;
}

export interface NetworkSummary {
  status: EdgeStatus;
  label: string;
  operational: number;
  total: number;
  avgUptime: number;
}

// Function to derive summary from nodes
export function getNetworkSummary(nodes: EdgeNode[]): NetworkSummary { ... }

  5. Define data for the Analytics Map block

    main

    The Analytics Map block uses specific TypeScript interfaces to structure geographic, temporal, and categorical data. Use these interfaces to ensure your data is compatible with the block's visualization components.

    LocationPoint

    Used for mapping specific geographic points. Requires:

    • city: string
    • lng: number
    • lat: number
    • size: number (determines marker scale)

    BreakdownRow

    Used for categorical data lists (e.g., visited pages, countries, referrers, or browsers). Requires:

    • label: string
    • value: number
    export interface LocationPoint {
  city: string;
  lng: number;
  lat: number;
  size: number;
}

export interface BreakdownRow {
  label: string;
  value: number;
}

  6. Configure chart styles for Analytics Map

    main

    When providing data for charts within the Analytics Map block, you can use ChartConfig to define labels and CSS variables for colors.

    Example configurations found in the block:

    • usersPerDayChartConfig: Maps the users key to a label and a CSS variable color.
    • deviceCategoryChartConfig: Maps specific device keys (desktop, mobile, tablet) to their respective labels and colors.
    export const usersPerDayChartConfig = {
  users: {
    label: "Users",
    color: "var(--chart-2)",
  },
} satisfies ChartConfig;

export const deviceCategoryChartConfig = {
  desktop: { label: "Desktop", color: "var(--chart-1)" },
  mobile: { label: "Mobile", color: "var(--chart-2)" },
  tablet: { label: "Tablet", color: "var(--chart-3)" },
} satisfies ChartConfig;

  7. Define data for the Delivery Tracker block

    main

    To implement or customize a Delivery Tracker block, you need to provide data structures for meals, route coordinates, map viewport, and route styling.

    Meal Data

    Each meal must follow the DeliveryMeal interface:

    • name: string
    • price: string
    • quantity: number

    Route and Map Configuration

    • Coordinates: Define pickup (origin) and dropoff (destination) using { lng: number, lat: number } objects.
    • Map View: Configure the mapView object with center (as [number, number]), zoom, minZoom, and maxZoom.
    • Progress: Use progressFraction (a number between 0 and 1) to represent the portion of the route covered.

    Route Styling

    Route lines are styled using concrete hex colors (WebGL cannot use CSS variables). The routeStyle object supports:

    • progress: The covered path (includes color, width, and opacity).
    • remaining: The path ahead (includes width, opacity, and a color object with light and dark hex values).
    export interface DeliveryMeal {
  name: string;
  price: string;
  quantity: number;
}

export const pickup = { lng: -122.4185, lat: 37.7645 };
export const dropoff = { lng: -122.434, lat: 37.7475 };

export const mapView = {
  center: [-122.4263, 37.756] as [number, number],
  zoom: 13.6,
  minZoom: 12,
  maxZoom: 15,
};

export const routeStyle = {
  progress: { color: "#3b82f6", width: 6, opacity: 0.95 },
  remaining: {
    width: 5.2,
    opacity: 0.5,
    color: { light: "#6b7280", dark: "#9ca3af" },
  },
} as const;

  8. Use getNetworkSummary to calculate network health

    main

    The getNetworkSummary function takes an array of EdgeNode objects and returns a NetworkSummary object containing the aggregated status, a human-readable label, the count of operational nodes, the total node count, and the average uptime.

    Status logic:

    • If any node is "down", the network status is "down" (Label: "Partial outage").
    • If no nodes are down but some are "degraded", the network status is "degraded" (Label: "Degraded performance").
    • Otherwise, the status is "operational" (Label: "All systems operational").